>_SMTPBoxDOCUMENTATION

SMTPBox REST API reference

API endpoints for inboxes, message search, waiting for email, message bodies, headers, attachments and usage.

08 / REST API

API reference

All endpoints use https://api.smtpbox.dev, JSON responses and a Bearer API key. Successful responses contain success: true and data; errors contain success: false and an error object.

GET/v1/inboxes

List inboxes

POST/v1/inboxes

Create an inbox

GET/v1/inboxes/{inbox_id}

Get an inbox

PATCH/v1/inboxes/{inbox_id}

Rename or disable an inbox

DELETE/v1/inboxes/{inbox_id}

Delete an inbox

GET/v1/inboxes/{inbox_id}/messages

List the latest 50 messages

DELETE/v1/inboxes/{inbox_id}/messages

Clear an inbox

GET/v1/inboxes/{inbox_id}/messages/wait

Wait up to 25 seconds for a match

GET/v1/messages/{message_id}

Get message metadata

GET/v1/messages/{message_id}/{html|text|raw}

Get a message body

GET/v1/messages/{message_id}/headers

Get parsed headers

GET/v1/messages/{message_id}/attachments

List attachments

GET/v1/attachments/{attachment_id}

Download an attachment

DELETE/v1/messages/{message_id}

Delete a message

GET/v1/usage

Read plan and current usage

Create an inbox

Request
curl -X POST https://api.smtpbox.dev/v1/inboxes \
  -H "Authorization: Bearer sbx_api_your_key" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"prj_your_project","name":"CI"}'

Filter and wait for messages

The list endpoint accepts search, matching sender, recipient or subject. For test suites, the wait endpoint accepts to and subject substring filters and checks the latest 50 messages until the first match arrives. timeout is clamped to 1–25 seconds.

Wait request
curl "https://api.smtpbox.dev/v1/inboxes/box_123/messages/wait?timeout=20&to=qa%40example.test&subject=Reset" \
  -H "Authorization: Bearer sbx_api_your_key"

Updated