echo.email API

The API runs the same test as the website. A request creates a temporary address, the system under test sends one email to the address, and the API returns the report as JSON. The API is free, with no key and no signup. Limits apply per IP address.

Flow

Create an address with POST /v1/addresses.
Send one email to the returned address.
Poll GET /v1/addresses/{token} with the X-Echo-Key header every few seconds until the status is done.
Fetch the report with GET /v1/reports/{report_id}.

Each status request keeps the address alive. After 10 minutes without one, the mail server refuses mail to the address. Each address accepts one message, and reports are deleted after 24 hours.

Endpoints

Request	Answers
`POST /v1/addresses`	201 with the address, 429 `slow_down`
`GET /v1/addresses/{token}`	200 with the status, 404 `unknown_address`, 429 `slow_down`
`GET /v1/reports/{report_id}`	200 done or error, 202 still in analysis, 404 `unknown_report`, 429 `slow_down`

Errors come back as JSON with one field, for example {"error": "slow_down"}. The status request needs the key, either in the X-Echo-Key header or as ?k= in the URL. A wrong key and an expired address both answer 404.

Create an address

curl -X POST https://api.echo.email/v1/addresses

{
  "address": "lake.mother.column@echo.email",
  "token": "lake.mother.column",
  "key": "q3k7…",
  "idle_timeout_s": 600,
  "status_url": "https://api.echo.email/v1/addresses/lake.mother.column"
}

Check the status

curl -H 'X-Echo-Key: q3k7…' \
  https://api.echo.email/v1/addresses/lake.mother.column

{
  "status": "done",
  "report_id": "h2kq…",
  "report_url": "https://echo.email/r/h2kq…"
}

The status moves from waiting to received to done (or error). Once the email has arrived, the response carries report_id and report_url, the report page on echo.email.

Fetch the report

curl https://api.echo.email/v1/reports/{report_id}

A finished report returns digest and report. The digest holds the score, the SPF, DKIM and DMARC results, the TLS version, IPv6 readiness and the failing sender requirements. The report holds every check from the report page. A report still in analysis returns status 202.

Limits

Each IP address gets 30 new addresses and 120 status or report requests per minute. Over the limit, the API answers 429.

Every response carries Access-Control-Allow-Origin: *, so browser code on any site calls the API directly, with the X-Echo-Key header allowed.

MCP

AI agents use the same flow through the echo.email MCP server.