API Reference

Introduction

AssertMail gives you real email addresses you can create and destroy via API. The typical pattern in an integration test is:

1. Create an inbox — get back an email address.
2. Feed that address into your app and trigger the email send.
3. Long-poll the inbox until the email arrives (or timeout).
4. Assert on subject, body, links, whatever you care about.

Inboxes expire automatically at their TTL, so there's no cleanup to manage between runs. Parallel test workers can each create their own inbox with no coordination needed.

Authentication

All API requests require an API key passed in the Authorization header as a Bearer token. Create and manage your keys in the dashboard.

Authorization: Bearer j8Kp3mN9xR2vL5tQ7wY0aB4cD6eF1gH_zX

Key format

API keys are 43-character base64url strings generated when you create a key in the dashboard.

Keep keys secret

API keys are long-lived. Don't commit them to source control — use environment variables or a secrets manager and inject them into your test environment at runtime.

Quick start

The full flow as a shell script — create an inbox, trigger your app, poll for the result.

# 1. Create an inbox (TTL 5 minutes)
$ INBOX=$(curl -sX POST https://assertmail.com/api/inboxes \
    -H "Authorization: Bearer $ASSERTMAIL_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ttlSeconds":300}')

$ EMAIL=$(echo $INBOX | jq -r '.emailAddress')
$ ID=$(echo $INBOX | jq -r '.id')

# 2. Trigger your app's send flow
$ curl -sX POST https://yourapp.test/api/register \
    -d "{\"email\": \"$EMAIL\"}"

# 3. Long-poll until the email arrives (max 25s)
$ curl -s "https://assertmail.com/api/inboxes/$ID/emails?wait=25" \
    -H "Authorization: Bearer $ASSERTMAIL_KEY" \
  | jq '.emails[0].subject'

Base URL

All endpoints are relative to:

https://assertmail.com/api

All requests and responses use JSON. Set Content-Type: application/json on requests with a body.

Create inbox

$ curl -sX POST https://assertmail.com/api/inboxes \
    -H "Authorization: Bearer $ASSERTMAIL_KEY" \
    -H "Content-Type: application/json" \
    -d '{"ttlSeconds": 120, "allowedSenders": ["noreply@yourapp.com", "@yourapp.com"]}'

{
  "id":             "01JXKP7N3MQVW4RBSTDYFZ8EG2",
  "emailAddress":   "illustration-1234@in.assertmail.com",
  "allowedSenders": ["noreply@yourapp.com", "@yourapp.com"],
  "ttl":            1751000520
}

Delete inbox

$ curl -sX DELETE https://assertmail.com/api/inboxes/01JXKP7N3MQVW4RBSTDYFZ8EG2 \
    -H "Authorization: Bearer $ASSERTMAIL_KEY"

List emails

$ curl -s "https://assertmail.com/api/inboxes/$ID/emails?wait=25" \
    -H "Authorization: Bearer $ASSERTMAIL_KEY"

{
  "emails": [{
    "id":              "01JXKP8R2A4BNCVTSFGZ9MW1HK",
    "sender":         { "address": "noreply@yourapp.com", "name": "Your App" },
    "subject":        "Confirm your email address",
    "html":           "<p>Click <a href=\"...\">here</a> to confirm.</p>",
    "plaintext":     "Click the link to confirm: https://...",
    "truncated":     false,
    "attachmentNames": []
  }]
}

Continuous polling

If your test expects multiple emails, use the after cursor to only receive new ones. Take the id of the last email you processed and pass it back on the next call.

# First call — get everything currently in the inbox
$ RESULT=$(curl -s "https://assertmail.com/api/inboxes/$ID/emails?wait=25" \
    -H "Authorization: Bearer $ASSERTMAIL_KEY")

# Save the last email ID as a cursor
$ CURSOR=$(echo $RESULT | jq -r '.emails[-1].id // empty')

# Subsequent calls — only get emails received after the cursor
$ curl -s "https://assertmail.com/api/inboxes/$ID/emails?wait=25&after=$CURSOR" \
    -H "Authorization: Bearer $ASSERTMAIL_KEY"

Error codes

Errors return JSON with an error field describing what went wrong.

{
  "error": "Inbox not found"
}