Automated Spam Tests

An automated test runs a spam test on a recurring schedule (daily or weekly, on the weekdays and hour you choose) so you can monitor inbox placement over time without triggering each test manually.

Unlike a one-time spam test, where you send the email to the seedlist yourself, an automated test sends the email for you, from an account you have already connected to MailReach. You deliver the message you want to test to a dedicated MailReach inbox, and the platform takes care of the rest on every scheduled run.

The full setup flow is:

Connect the sending account (IMAP/SMTP or OAuth).
Create the automated test against that account to get a key.
Send the email you want to test to {key}@test.mailreach.co.
Configure the schedule: recurrence, hour, weekdays, seedlist, audience.
Optionally trigger a run on demand with run_now.

All endpoints are documented in full in the MailReach API reference.

Tip

Each run (scheduled or on-demand) consumes one Spam Checker credit. See pricing.

1. Connect the account

The sending account must be connected to your project first. Use either method from Connect an inbox:

POST /v1/imap_auth: for a single IMAP/SMTP account.
POST /v1/email_workspaces/{workspace_id}/accounts: to batch-connect Gmail or Outlook accounts via OAuth.

If the account is only used for spam testing and not for warming or monitoring, pass "spamchecker_only": true when connecting it. The account will not count as a warming seat.

Keep the returned account_id. You'll need it in the next step.

2. Create the automated test

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

{
  "account_id": 1234
}

The response includes:

id: used for every subsequent call (update, configure weekdays, run now, delete).
key: the unique token for the dedicated MailReach inbox where you'll send your email template.

Example response:

{
  "id": 54595,
  "key": "9a3a7e6a8aaa71",
  "subject": null,
  "content_text": null,
  "content_html": null,
  "automated_test_runs": [],
  "template_defined": false,
  "btoc": false,
  "btob": false,
  "accounts": [
    {
      "id": 758,
      "email": "aakashob9zeo84a1@outlook.com",
      "first_name": "Kashob",
      "last_name": "Aka"
    }
  ],
  "repeat_period": "WEEK",
  "repeat_period_delay": 1,
  "time_zone": "UTC",
  "utc_hour": null,
  "hour": null,
  "active": false,
  "last_run_at": null,
  "created_at": "2026-04-24T09:07:00.020Z",
  "can_show_run_now": true,
  "account_day_delta": 1920,
  "account_ids": [758],
  "seedlist": 0,
  "alerts": []
}

3. Send the email template

For every run, MailReach needs a copy of the message to forward to the seedlist. Provide it by sending (from any inbox) the exact email you want tested to:

{key}@test.mailreach.co

Use the key from the step above. For example, with "key": "9a3a7e6a8aaa71", send to 9a3a7e6a8aaa71@test.mailreach.co.

MailReach stores the latest message received at that address and uses it as the template on each run. Send a fresh email to the same address whenever you want to update the content being tested.

4. Configure the schedule

Update the test with POST /v1/automated_tests/{id}:

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

{
  "active": true,
  "repeat_period": "WEEK",
  "repeat_period_delay": 1,
  "hour": 9,
  "time_zone": "Europe/Paris",
  "seedlist": 0,
  "btob": true,
  "btoc": false
}

Key fields:

Field	Description
`repeat_period`	`WEEK` or `DAY`
`repeat_period_delay`	How many periods between runs (e.g. `WEEK` + `2` runs every two weeks)
`hour`	Local hour of the run (0–23), interpreted in `time_zone`
`time_zone`	IANA time zone string (e.g. `Europe/Paris`, `America/New_York`)
`seedlist`	`0` to `4`. `0` enables auto-rotation: each run uses a different seedlist, which is recommended to avoid skewed results
`btob` / `btoc`	Set the audience that matches your real recipients. See btob vs btoc
`active`	Set to `false` to pause the schedule without deleting the test

Restricting to specific weekdays

By default, a test runs on any day matching its recurrence. To limit it to specific weekdays, use POST /v1/automated_tests/{id}/runs:

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

{
  "weekdays": [1, 3, 5]
}

Weekdays follow ISO convention: 0 = Sunday, 1 = Monday, …, 6 = Saturday. This call replaces any previously configured weekdays.

5. Trigger a run on demand

Run the test immediately, independently of its schedule:

POST https://api.mailreach.co/api/v1/automated_tests/42/run_now
X-Api-Key: Bearer YOUR_API_KEY

Each on-demand run consumes one Spam Checker credit and requires at least one live account linked to the test.

Warm-up safety check

If the sending account is also being warmed by MailReach, a run will be skipped automatically when the account or its domain is younger than ~14 days of warming. This prevents spam tests from an inbox whose reputation is still being built, which could otherwise damage deliverability.

Once the account has enough warming history, scheduled and on-demand runs resume normally.

Tip

Subscribe to the "Automated spam test completed" webhook event to get notified when each run finishes. See Webhooks & Alerts.

Credits

Each run (scheduled or triggered via run_now) consumes one Spam Checker credit. See pricing.

One-Time Spam Test

Connect an Inbox