Spam Handling
How Octocom decides what is spam, what happens to spam conversations, how a misjudged customer comes back, and how to tune and test the spam filter from the dashboard, MCP or the REST API.
Every public support inbox receives spam: sales pitches, newsletters, automatic replies, phishing. Octocom's spam filter decides whether an email is spam or a customer message, and you can see, tune and test how it decides.
- Spam is created closed, handed off and tagged
spam. It stays out of every queue, nobody is assigned, and the AI agent does not answer it. You find it in the built-in Spam view. - Customer messages are handled normally.
The filter leans towards customer. Anything that could be a customer trying to get help is a customer message, even when it is short, unclear or empty. Missing a real customer is worse than the AI agent answering a spam email.
Settings are under Settings -> Help Desk -> Spam Filter.
What happens to a new email
The filter judges the first email of each new conversation, on inboxes with Spam Detection switched on (Settings -> Channels -> Email). It checks in this order and stops at the first answer:
- Automatic replies and bounces. Headers or subjects that mark an out-of-office reply, a bounce or a delivery report, and automated sender addresses such as
no-reply@ormailer-daemon@. - Your spam rules. Email rules with the Mark as spam action, matching the sender, domain, subject or an AI prompt.
- The AI. It reads the sender, the receiving inbox, the subject and what the sender wrote, and decides using Octocom's base policy plus your instructions.
Email rules that ignore, forward or hand off an email run before the filter. A handed-off email is not checked for spam: a person is already handling it.
When an email is marked spam, the conversation timeline says why, for example "Classified conversation as spam: A sales pitch for SEO services, which the policy lists as spam."
When a spam conversation gets a later email
A misjudged customer usually writes again. So when the filter labelled a conversation spam, it checks the customer's next emails too:
- How it judges: the AI is told the conversation's first email was classified spam, and why, so a follow-up that only continues a pitch ("any update?") stays spam, while a customer's real request lifts it.
- Not spam: the conversation leaves spam. The
spamtag is removed, the timeline says "Reclassified conversation as customer", and the conversation reopens for your team. It stays handed off, so a person answers, not the AI agent. With an external help desk, the ticket there stays the source of truth. - Still spam: nothing changes.
- Limit: re-checking stops once the conversation holds 5 customer messages. Long spam threads are automated back-and-forth; a real customer shows up within the first few follow-ups.
Later emails are not re-checked when:
- someone marked or unmarked the conversation as spam by hand. A person's decision stands;
- a sender, domain, subject or AI prompt spam rule matches. Those keep a sender in spam for good;
- the inbox has spam detection switched off, or is a Zendesk inbox (Zendesk filters its own spam);
- the AI cannot be reached. The label stays as it is.
Marking and unmarking by hand
In a conversation, use Mark as spam or Unmark as spam in the menu.
- Mark as spam closes the conversation, hands it off and clears the assignee. The filter never re-checks it.
- Unmark as spam turns it back into a customer conversation and reopens it.
- Marking a conversation does not block the sender. To keep a sender or domain in spam for good, add an email or domain rule with Mark as spam. To stop the filter misjudging a kind of email, add an instruction (below).
Every view except Spam hides spam. Use the Spam filter on a view to include it, and spam=true or spam=false on the REST conversation list.
Base policy and your instructions
The base policy is the same for every business and improves over time. It is shown read-only on the Spam Filter page and returned by get_spam_filter. In short:
- Customer messages: anything that could be a customer, or someone interested in becoming one, trying to get help or ask something, including short, unclear, one-word or empty emails (the message may be in the subject); unsubscribe requests; replies to your own promotions and order emails; buying and wholesale enquiries; contact forms; lawyers, authorities, banks and journalists writing about the business.
- Spam: sales pitches and cold outreach, newsletters and promotions from other companies, automated emails such as receipts and password resets, automatic replies, phishing and gibberish.
Your instructions are added after the base policy and win where they conflict. Write them in plain language, as exceptions for your business, in either direction:
Our customers often write very short complaints such as "this is not working"
or "not this" from personal Gmail or Outlook addresses. These are customer
messages, never spam.
Emails from our warehouse (logistics@ourwarehouse.example) are customer
messages.
Newsletters from our fulfilment provider sent to all its merchants are spam,
unless they name one of our orders or customers.Up to 5,000 characters. Remove them to go back to the base policy alone.
What does not belong here
The filter only decides spam or not spam. To route other kinds of email, use email rules:
| You want to | Use |
|---|---|
| Hand lawyers, authorities or press to the team | An AI email rule with Hand off |
| Tag marketplace notifications or wholesale requests | An email rule with Add tag |
| Send invoices to finance | An email rule with Forward |
| Drop an address completely | An email rule with Ignore |
| Always mark one sender or domain as spam | An email or domain rule with Mark as spam |
Describe kinds of spam in your instructions rather than in AI email rules with Mark as spam: the filter weighs your instructions together with the base policy and records its reason.
Testing
Test every change before saving it. On the Spam Filter page, edit the instructions, then:
- Test an email: paste a sender, subject and message, optionally choosing the receiving inbox.
- Replay conversations: paste conversation links or IDs (up to 25). Each is classified again from its first email and compared with how it is classified now, so you can see what your draft would change.
Each result shows spam or customer, the step that decided and the reason. Tests never change conversations, send emails or apply tags. AI results can vary slightly between runs, so test a handful of examples on both sides: the emails you want to fix, and a few that are already right.
A replay cannot repeat the header check for automatic replies, because headers are not stored. On an inbox with Spam Detection switched off, a test still shows what the filter would decide.
Through MCP and the REST API
| MCP | REST | What it does |
|---|---|---|
get_spam_filter | GET /rest/v1/spam-filter | The base policy and your instructions. |
update_spam_filter | PATCH /rest/v1/spam-filter | Sets your instructions; null or an empty string removes them. |
test_spam_filter | POST /rest/v1/spam-filter/test | Tests an email or up to 25 conversationIds, with draft instructions. |
Test results have the same shape everywhere: classification, decidedBy, reason, spamDetectionEnabled and, for conversations, savedClassification and changed. Changes to the instructions are recorded in the configuration history from every interface. Reading needs the helpdesk:read scope; changing and testing need helpdesk:write, and replaying conversations also needs conversations:read.
A good workflow for an agent: collect the conversations that were wrongly marked spam (or wrongly let through) from the Spam view, replay them with a draft, replay a few correct ones with the same draft, then save it with update_spam_filter.
Other channels
- Facebook and Instagram direct messages have their own spam check on the first message of a conversation. It is conservative and has no settings yet.
- External help desks such as Zendesk, Gorgias or Freshdesk: a ticket marked spam there is left alone by Octocom.
- Web chat, WhatsApp and SMS have no spam filter. Web chat is protected by rate limits instead.