API Reference

A REST API for the part of email testing that has no browser: the CI job. Create an inbox for the run, point the application at it, wait for the message, assert on it, tear down.

What it covers

Everything a pipeline step needs, and little else. Inboxes can be created and destroyed per run — ephemeral ones expire on their own and do not count against your plan. A single call blocks until the message arrives, or returns a verdict on it: subject, links, one-time code, unrendered template variables, deliverability score. Around that sit the reads (list, search, raw download, attachments), a share link for the pull request, and webhooks you can manage from a script.

What it deliberately does not do: send mail, or expose the app's session conveniences such as read state. Nothing sent through Mailclutch ever reaches a real recipient, and the API keeps that promise too.

Sections

Sections of the API reference
Section	Covers
Authentication & scopes	Organization-owned tokens, the scope grammar, inbox binding and expiry.
Conventions	Identifiers, cursor pagination, idempotency keys, errors and rate limits.
Inboxes	List, read, create — permanent or ephemeral with a TTL — and delete inboxes.
Emails	List, search, read, download, extract links and codes, score, delete, purge.
Wait & expect	Block until a message arrives, or get a pass/fail verdict on it in one call.
Share links	A public URL to one captured message, for a pull request or a ticket.
Webhooks	Create and manage webhooks from a script, and read their delivery history.
CI recipes	A complete GitHub Actions job, and the shape of a test that uses the API.

Base URL

https://app.mailclutch.com/api/v1

Every request carries a bearer token and asks for JSON. Identifiers are opaque strings; timestamps are ISO 8601 in UTC.

Authorization: Bearer <your-token>
Accept: application/json
Content-Type: application/json

A first run, end to end

Three calls. Create an inbox that lives thirty minutes, trigger whatever sends the mail with the SMTP pair you got back, then ask for a verdict. The last call exits non-zero when the message is late or wrong, which is all a pipeline step needs.

API=https://app.mailclutch.com/api/v1
AUTH="Authorization: Bearer $MAILCLUTCH_TOKEN"

# 1. An inbox for this run. Idempotent on retry.
INBOX=$(curl -sS --fail "$API/inboxes" -H "$AUTH" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CI_RUN_ID" \
  -d '{"name":"pr-482","ttl":"30m"}')
INBOX_ID=$(echo "$INBOX" | jq -r .id)
export SMTP_HOST=$(echo "$INBOX" | jq -r .smtp.host)
export SMTP_USER=$(echo "$INBOX" | jq -r .smtp.username)
export SMTP_PASS=$(echo "$INBOX" | jq -r .smtp.password)

# 2. Run the thing that sends mail.
npm run test:signup

# 3. The verdict. Non-zero exit if nothing matching arrives in 30 s, or a check fails.
curl -sS --fail "$API/inboxes/$INBOX_ID/expect" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"timeout":30,"expect":{"subject_contains":"Verify your email","has_link_matching":"^https://app\\.example\\.com/verify/","no_unrendered_variables":true}}'

The inbox is gone on its own thirty minutes later; a DELETE at the end of the job just makes it sooner. The CI recipes page has the same thing as a GitHub Actions job.

Agents

A coding agent should not need a token at all: the MCP server exposes the same capabilities — wait, extract, score, share — with no account, and hands the agent its own inbox. The API is for the pipeline; MCP is for the conversation.