Email Inboxes

Email inboxes let your tests receive email and inspect the messages programmatically. Use these endpoints to list inboxes, poll for new messages, read message content, and clean up inboxes when you are done.

All email inbox endpoints require the x-api-key header. They do not require x-project-id — inboxes are org-scoped, not project-scoped.

For inbox management (creating inboxes) and the console workflow, see Email Inboxes.

Limits

Limit	Value
Inboxes per organization	5
Messages per inbox	1 000 (oldest messages are evicted when the limit is reached)
Message retention	12 hours
Body size	128 KB per field (`bodyText`, `bodyHtml`)

List inboxes

GET /v1/email-inboxes

Scope: emailInbox:read

Returns all inboxes in your organization.

Response

{
  "data": [
    {
      "id": "01932f1a-0000-7000-a000-000000000001",
      "address": "a1b2c3d4e5f6g7h8@inbox.smoothdeploy.com",
      "name": "signup-flow",
      "createdAt": "2026-09-01T10:00:00.000Z",
      "messageCount": 3
    }
  ]
}

Field	Notes
`id`	UUID of the inbox
`address`	Full email address to send messages to
`name`	Optional display name set when the inbox was created
`createdAt`	ISO 8601 timestamp
`messageCount`	Number of messages currently stored in the inbox

Get limits

GET /v1/email-inboxes/limits

Scope: emailInbox:read

Returns the inbox limits that apply to your organization.

Response

{
  "data": {
    "maxPerOrg": 5,
    "maxMessages": 1000,
    "messageRetentionHours": 12,
    "bodyMaxBytes": 131072
  }
}

List messages

GET /v1/email-inboxes/:inboxId/messages

Scope: emailInbox:read

Returns all messages in an inbox, ordered newest first. The :inboxId path segment accepts either the inbox UUID or its full email address.

Query parameters

Parameter	Type	Notes
`since`	ISO 8601 datetime (optional)	Return only messages received at or after this time. Useful for polling. Example: `2026-09-01T10:05:00.000Z`

Response

{
  "data": [
    {
      "id": "01932f1a-0000-7000-b000-000000000002",
      "fromAddress": "noreply@example.com",
      "subject": "Confirm your email address",
      "bodyText": "Click here to confirm: https://example.com/confirm?token=abc123",
      "bodyHtml": "<p>Click <a href=\"https://example.com/confirm?token=abc123\">here</a> to confirm.</p>",
      "receivedAt": "2026-09-01T10:04:30.000Z",
      "urls": ["https://example.com/confirm?token=abc123"]
    }
  ]
}

Field	Notes
`id`	UUID of the message
`fromAddress`	Sender address
`subject`	Email subject line
`bodyText`	Plain-text version of the body
`bodyHtml`	HTML version of the body
`receivedAt`	ISO 8601 timestamp when the message arrived
`urls`	All `https://` and `http://` links extracted from `bodyHtml`. Useful for grabbing confirmation links without parsing HTML.

Example — poll until a message arrives

API_KEY="sd_..."
ORG="https://api.smoothdeploy.com"
INBOX_ID="01932f1a-0000-7000-a000-000000000001"
SINCE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

while :; do
  COUNT=$(curl -s "$ORG/v1/email-inboxes/$INBOX_ID/messages?since=$SINCE" \
    -H "x-api-key: $API_KEY" | jq '.data | length')
  [ "$COUNT" -gt 0 ] && break
  sleep 2
done

curl -s "$ORG/v1/email-inboxes/$INBOX_ID/messages?since=$SINCE" \
  -H "x-api-key: $API_KEY" | jq '.data[0].urls[0]'

Get message

GET /v1/email-inboxes/:inboxId/messages/:messageId

Scope: emailInbox:read

Returns a single message by ID. :inboxId accepts a UUID or full email address.

Response

{
  "data": {
    "id": "01932f1a-0000-7000-b000-000000000002",
    "inboxId": "01932f1a-0000-7000-a000-000000000001",
    "organizationId": "01932f1a-0000-7000-c000-000000000003",
    "sesMessageId": "0100018f2c3d4e5f-example-000000",
    "fromAddress": "noreply@example.com",
    "subject": "Confirm your email address",
    "bodyText": "Click here to confirm: https://example.com/confirm?token=abc123",
    "bodyHtml": "<p>Click <a href=\"https://example.com/confirm?token=abc123\">here</a> to confirm.</p>",
    "receivedAt": "2026-09-01T10:04:30.000Z",
    "createdAt": "2026-09-01T10:04:31.000Z"
  }
}

Note: the single-message response does not include urls. Parse bodyHtml directly if you need links.

Returns 404 if the message does not exist or belongs to a different inbox or organization.

Delete inbox

DELETE /v1/email-inboxes/:inboxId

Scope: emailInbox:delete

Permanently deletes an inbox and all its messages. :inboxId accepts the inbox UUID or its full email address.

Requires an active subscription. A lapsed or missing subscription returns 403 { "message": "LICENSE_REQUIRED" }.

Response

{ "data": null }

Returns 404 if the inbox does not exist in your organization.

On this page