Email API

Endpoints for email inboxes and the messages they capture. Authentication, roles, errors and paging are described in the API overview.

#Inboxes

#Create an inbox

curl -X POST https://app.testlie.com/api/inboxes \
  -H "Authorization: Bearer $TESTLIE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "ci-run-4812", "expiresInMinutes": 60 }'

{
  "inbox": {
    "id": "cm1x9k2v80000abcd",
    "name": "ci-run-4812",
    "projectId": null,
    "emailAlias": "k2m9v0q3x7",
    "inboundAddress": "k2m9v0q3x7@in.testlie.com",
    "maxMessages": 500,
    "expiresAt": "2026-10-23T11:30:00.000Z",
    "createdAt": "2026-10-23T10:30:00.000Z",
    "messageCount": 0,
    "unreadCount": 0,
    "smtp": { "host": "smtp.testlie.com", "ports": [587, 2525, 465], "username": "…", "password": "…", "auth": ["PLAIN", "LOGIN"], "tls": true }
  }
}

Creating more inboxes than the plan allows answers 402 with "code": "quota_exceeded".

#Events stream

GET /api/inboxes/:id/events keeps the connection open and sends text/event-stream events as JSON in data: lines:

A comment line (: ping) is sent every 25 seconds to keep proxies from closing the connection. For tests, the wait endpoint is simpler.

#Messages

Summaries in lists and in wait have id, inboxId, subject, from ({ address, name }), to and cc (arrays of { address, name }), envelopeTo (the SMTP recipients), size, isRead and receivedAt. The full message adds messageId (the Message-ID header), bcc (envelope recipients not in To or Cc), envelope ({ from, to }), html, text, headers and attachments (id, filename, contentType, size, contentId, inline).

#Wait for a message

GET /api/inboxes/:id/messages/wait answers as soon as a matching message is stored:

curl -f -H "Authorization: Bearer $TESTLIE_API_KEY" \
  "https://app.testlie.com/api/inboxes/$INBOX_ID/messages/wait?to=new-user@example.com&subject=Welcome&since=2026-10-23T10:30:00Z"

{
  "message": {
    "id": "k2m9v0q3…",
    "inboxId": "cm1x9k2v80000abcd",
    "subject": "Welcome aboard",
    "from": { "address": "app@example.com", "name": "Example App" },
    "to": [{ "address": "new-user@example.com", "name": "" }],
    "cc": [],
    "envelopeTo": ["new-user@example.com"],
    "size": 18234,
    "isRead": false,
    "receivedAt": "2026-10-23T10:30:04.512Z"
  }
}

With several matches it returns the newest. On timeout it answers 408 { "error": "No matching message before the timeout" }. Testing in CI shows it in Playwright, pytest and GitHub Actions.

#Extract links and codes

GET /api/messages/:id/extract finds what a test usually wants from an email, best match first:

{
  "messageId": "k2m9v0q3…",
  "subject": "Your sign-in code",
  "codes": [{ "value": "482913", "context": "Your sign-in code is 482913", "score": 12 }],
  "magicLinks": [{ "url": "https://app.example.com/verify?token=…", "text": "Verify email", "reason": "text and URL mention verify", "score": 9 }],
  "links": [{ "url": "https://app.example.com/verify?token=…", "text": "Verify email" }]
}

links has every link in the HTML and text parts. Known tracking redirects are unwrapped; the link then also has originalUrl. magicLinks are the links that look like verify, reset, sign-in or invite links. Read-only keys may call it. The SDKs wrap it.

#Forwarding

Forwarding sends captured mail to real addresses. Every address must first be confirmed by its owner, and the plan must include forwarding (Team and above). See Forwarding.

Forwarded recipients count toward the plan's daily limit (402 when it is used up).

#Inbound email to your app

Simulate email arriving at your app as SendGrid, Mailgun or Postmark would post it. Details and payloads are in Inbound SMS & email to your app.

A simulated email counts toward the monthly message quota (402 when it is used up).