What to do with a spam verdict
The API tells you spam or ham and why. The part that decides whether your customers notice is what your code does next. A policy that has held up across many forms.
A verdict is only useful if it turns into a decision. Most integrations start with “if spam, drop it”, find out a week later that a real inquiry vanished, and then swing to “if spam, deliver anyway with a warning”, which is the same as no filter. Here is the policy we recommend, and why it has three branches rather than two.
Branch one: drop silently
Some reason codes describe bots, not judgement calls. HONEYPOT_FILLED means a field no human can see was filled in. FAST_SUBMIT means the form was posted a second after it loaded. DUP_KNOWN_SPAM means the identical text was already caught elsewhere. IP_REPUTATION_BAD and EMAIL_REPUTATION_BAD mean the sender has a recent record across several sites.
For these, return the same “thanks, we will be in touch” page you show everyone, send nothing, and do not tell the bot it was caught. Nobody is waiting for a reply.
Branch two: hold for review
ML_SPAM and LLM_SPAM are judgement calls. They are right far more often than not, but they are the branch where a real message could sit. Put these in a folder you look at once a week, show the reason next to each one, and give yourself a one-click “not spam”. Wire that click to the feedback endpoint so the same sender and the same message are delivered next time.
On the visitor’s side, show the normal confirmation plus a plain email address as a fallback. Real people who do not hear back will use it; bots never do.
Branch three: deliver
Everything else. Optionally log the reason codes alongside the message, so when a customer asks “why did this one get through” you have an answer.
Two rules that make this safe
Fail open. If spamex is unreachable, times out, or your quota is exhausted, deliver the message. Losing one customer costs more than a day of spam.
Never hold silently. The review folder only works if someone reads it. If nobody will, deliver borderline messages with a label instead; a flagged email beats a lost one.
For platforms
The same three branches map onto your product: a Spam tab with reasons, a “Not spam” button that calls feedback, and delivery as the default. Your customers get a filter they can see and correct, which is the difference between “your filter ate my lead” and “thanks, that one was spam”.