Usage

One-Time Spam Test

A spam test measures where your email lands (inbox, promotions, or spam) across a seedlist of Gmail and Outlook addresses. It also reports authentication results (SPF, DKIM, DMARC), content analysis, and blacklist hits on your sending IP and links.

Running a test through the API is a three-step flow:

  1. Create the test to get a public_full_id and the seedlist addresses.
  2. Send your email to every seedlist address, with public_full_id embedded in the body so MailReach can match it to your test.
  3. Poll for the result until completed is true.

All endpoints are documented in full in the MailReach API reference. This page walks through the happy path.

Tip

Each test consumes one Spam Checker credit. See pricing. Credits are not charged if the test fails to collect results.

1. Create the test 

POST https://api.mailreach.co/api/v1/spam_tests
X-Api-Key: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "seedlist": 1
}

seedlist is optional (values 1 to 4, default 1) and selects which seedlist variant to use. Rotating between variants across tests reduces the risk of any single seedlist skewing your results.

The response contains:

  • public_full_id: the identifier you must embed in the body of the email you send (e.g. mr_abc123...). This is how MailReach attributes incoming emails to your test.
  • public_id: the short identifier used to poll the result.
  • results[]: one entry per seedlist address with email, first_name, and provider (gmail or outlook). These are the recipients you send to.

2. Send your email to the seedlist

Send the email you want to test from the sending setup you want to measure: your own ESP, SMTP server, or inbox. Requirements:

  • To: every email from the results[] array returned above.
  • Body: must contain the public_full_id string somewhere in the message (plain text or HTML).

MailReach collects each email as it arrives on the seedlist mailboxes and scores the test. The test typically completes within a few minutes, depending on delivery speed.

Warning

Send from the exact setup you want to test: the same domain, IP, and ESP you use in production. Sending from a different setup will not reflect your real deliverability.

3. Fetch the result

Poll the test until completed is true:

GET https://api.mailreach.co/api/v1/spam_tests/{public_id}
X-Api-Key: Bearer YOUR_API_KEY

We recommend polling every 10–15 seconds. Most tests complete within 3–5 minutes.

The response includes:

Field Description
completed true when all seedlist results have been collected
score Overall deliverability score (0–100)
btob_score Score against professional inboxes (Google Workspace, Microsoft 365)
btoc_score Score against personal inboxes (Gmail, Outlook.com, Hotmail)
analysis_results Per-seedlist placement: inbox, categories, spam, or missing
blacklist_sending_ip Blacklist hits on the sending IP
blacklist_links Blacklist hits on links inside the email
summary Human-readable summary of the findings

Understanding btob_score vs btoc_score

Professional (B2B) and personal (B2C) inboxes apply different spam filters, so the two scores can diverge significantly for the same test.

  • btob_score: computed only against Google Workspace and Microsoft 365.
  • btoc_score: computed only against Gmail.com, Outlook.com, and Hotmail.

Use the score that matches your actual audience. If you send to business email addresses, btoc_score is not meaningful for you, and vice versa.

Tip

You can change the audience scoring after the fact with POST /v1/spam_tests/{public_id}: pass "audience": "btob", "btoc", or "all".

Credits

Each test consumes one Spam Checker credit. See pricing.

Next steps

Previous
Quickstart
Next
Automated Spam Tests