Classifier

Mails.ai’s check on every send before delivery: fixed rules, then an LLM judge, against a transactional-only policy. Each send’s response carries classifier_score, and a refused send answers 422 with its reason.

The classifier runs between your agent.send() call and delivery. Mails.ai carries transactional mail only, so each automatic mail send is read before it leaves, and cold or bulk mail is refused instead of delivered.

How a send is checked

1. Fixed rules first. They refuse the clear cases outright: prohibited content, text written to steer the classifier, phishing links that warn of a locked or lost account, and, outside a reply, cold or spam phrases stacked in one message. A refusal from these rules can’t be appealed.
2. Then an LLM judge. It reads the whole message against the cold and bulk policy and decides whether it is transactional: a receipt, a password reset, a verification code, a reply to a message the recipient sent. A first message to someone who has never written to you is judged more strictly. Unsubscribe and list language counts as strong evidence of bulk mail, though a digest the recipient subscribed to, such as a daily report or a price alert, still passes.

Mail sent only to your own workspace’s addresses skips the cold checks. The rules on content still apply.

What your code sees

Every send’s response carries classifier_score, from 0 for clean to 1 for cold or spam. A refused send answers 422 with the code cold_email_prohibited and a message that names what it was classified as, and with what confidence. To check a message without sending it, send it with a test key (mk_test_…): it is classified and the verdict comes back, but nothing is transmitted or billed.

Disagreeing with a refusal

A refusal by the LLM judge can be appealed: press “Ask for a second review” in the dashboard, or send the same agent, subject and body to POST /v1/messages/appeal. An independent reviewer judges the message again under the same policy, and if it clears, the identical message sends normally for 24 hours. Appealing the same content again gets the same answer, and a workspace can appeal 10 times in 24 hours.

See the architecture page for where the classifier sits in the send pipeline, or the sender reputation glossary entry for how per-agent reputation is built.