Skip to main content

Quick Start

Sign in, mint a token, create a mailbox, read its inbox — end to end in a minute.

0. Get a token​

  1. Sign in at mail.td/pro/login with Google or GitHub. An account is created on first sign-in.
  2. In the Dashboard, click Create API token and copy the value. It starts with td_ and is shown only once.

Export it for the rest of this guide:

export TD_TOKEN="td_xxxxxxxxxxxxxxxxxxxx"

1. Pick a domain​

curl https://api.mail.td/api/domains

Response:

{
  "domains": [
    {
      "id": "38b711da-77bf-4e15-a3d6-ff5c1ae0498f",
      "domain": "example.com",
      "default": true,
      "sort_order": 0,
      "pro_only": false
    }
  ]
}

2. Create a mailbox​

curl -X POST https://api.mail.td/api/accounts \
  -H "Authorization: Bearer $TD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address": "hello@example.com", "password": "s3cret"}'

Response:

{
  "id": "01H4Z2VC9T7WRX8VY5K3M7A2F1",
  "address": "hello@example.com",
  "token": "eyJhbGciOi..."
}

The response token is a per-mailbox bearer credential. You can use it on the mailbox-scoped endpoints below, or you can keep using your account-level $TD_TOKEN — both work.

3. List messages​

The mailbox's account_id in the URL accepts either its UUID or its email address:

curl https://api.mail.td/api/accounts/hello@example.com/messages \
  -H "Authorization: Bearer $TD_TOKEN"

Response:

{
  "messages": [
    {
      "id": "01H...ABC",
      "sender": "noreply@example.com",
      "subject": "Welcome",
      "created_at": "2026-04-17T10:22:00Z",
      "is_read": false
    }
  ],
  "page": 1
}

4. Read a message​

curl https://api.mail.td/api/accounts/hello@example.com/messages/01H...ABC \
  -H "Authorization: Bearer $TD_TOKEN"

Returns the full message with text_body, html_body, and attachments[].

Next steps​