Skip to main content

Spam pre-flight

Score a message the way a receiving server will, before you send it. No other email API offers this, and it is the fastest way to find out that a template will land in spam while you can still change it.

Check without sending​

curl https://api.epostix.com/v1/emails/check \
  -H "Authorization: Bearer $EPOSTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Your order has shipped",
    "html": "<h1>On its way</h1><p>Track it here.</p>"
  }'

Nothing is sent, nothing is charged.

{
  "score": 1.2,
  "threshold": 5,
  "verdict": "pass",
  "rules": [
    {"name": "MISSING_TEXT_PART", "score": 0.8, "description": "No plain text alternative", "suggestion": "Add a text version"}
  ],
  "issues": [
    {"code": "no_text_part", "severity": "warning", "message": "This message has no plain text part", "suggestion": "Send text alongside html"}
  ],
  "details": {"has_text_part": false, "has_html_part": true, "link_count": 1, "image_count": 0}
}

Reading it​

score against threshold. Lower is better. Over the threshold and most receiving servers will treat it as spam.

rules is the per-rule breakdown, and it is where the score comes from. A rule with a score of 0.8 contributed 0.8. This is what to fix, in descending order of score.

issues is our own analysis rather than the spam filter's: a missing text part, no unsubscribe link, a bad text-to-HTML ratio. These often matter more for long-term deliverability than the score does.

Check as part of a send​

Add preflight to any send and the result comes back on the message:

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Your order has shipped",
  "html": "<h1>On its way</h1>",
  "preflight": {"spam_check": true, "validate": true}
}
{"id": "...", "preflight_result": {"spam_score": 1.2, "spam_action": "no_action", "validation_errors": []}}

Pre-flight annotates, it never blocks. The message is sent regardless, and the result is recorded alongside it. If you want a bad score to stop a send, call /v1/emails/check first and decide for yourself.

validate: true additionally checks every recipient address for structural problems, which catches a typo before it becomes a bounce.

Where it pays off​

The obvious use is CI. Score your templates on every build and fail the build when a score crosses a line you choose. That turns deliverability from something you discover after a campaign into something you catch in review.

It is also the right first move when a specific message is landing in spam and you do not know why: the rule breakdown usually names the cause in one call.