Developer docs

Authentication

Protected account endpoints accept `Authorization: Bearer TOKEN`. TOKEN can be a login JWT or an API key starting with `ms_`.

Authorization: Bearer ms_YOUR_API_KEY

Create mailbox

TTL values: `10m`, `1d`, `7d`, `30d`. Domain must be public and active. Custom local part supports latin lowercase, numbers, dot, dash and underscore.

curl -X POST https://tempmailito.shop/api/v1/mailboxes \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer ms_YOUR_API_KEY' \
  -d '{"ttl":"10m","localPart":"demo","domain":"tempmailito.shop"}'

Response includes `id`, `address`, `expiresAt`, `accessToken`, `shareToken`, `shareUrl`.

Read inbox and messages

curl 'https://tempmailito.shop/api/v1/mailboxes/MAILBOX_ID/messages?accessToken=ACCESS_TOKEN'

curl 'https://tempmailito.shop/api/v1/mailboxes/MAILBOX_ID/messages/MESSAGE_ID?accessToken=ACCESS_TOKEN'

Share links

curl -X POST 'https://tempmailito.shop/api/v1/mailboxes/MAILBOX_ID/share-link?accessToken=ACCESS_TOKEN'

curl -X DELETE 'https://tempmailito.shop/api/v1/mailboxes/MAILBOX_ID/share-link?accessToken=ACCESS_TOKEN'

Webhooks

Create webhooks in `/profile`. The delivery request includes `x-tempmailito-signature`, an HMAC-SHA256 hex digest of the raw JSON payload using your webhook secret.

{
  "event": "message.received",
  "mailbox": "demo@tempmailito.shop",
  "message": {
    "id": "message_public_id",
    "from": "Sender <sender@example.com>",
    "to": "demo@tempmailito.shop",
    "subject": "Hello",
    "receivedAt": "2026-04-30T00:00:00.000Z"
  }
}

Common errors

• `domain_not_available` — domain is hidden, disabled or not guest-enabled.
• `ttl_not_allowed` — TTL exceeds domain or plan limit.
• `mailbox_name_taken` — local part already exists on that domain.
• `domain_mailbox_limit_exceeded` — active mailbox cap reached.
• `unauthorized` — missing/invalid JWT or API key.