Appearance

Quick Start ​

Get up and running with Mail.td API in under a minute.

Base URL ​

https://api.mail.td

Unified API ​

Authenticated API requests require a Pro API Token (td_...). Sign in with Google or GitHub and create one in the Pro Dashboard. Domain listing (GET /api/domains) is public and does not require authentication.

GET  /api/domains                              → pick a domain
POST /api/accounts                             → create account, get account_id
GET  /api/accounts/{account_id}/messages       → read emails

{account_id} is the email address

All API paths that contain {account_id} accept the email address directly, e.g. myname@mail.td. You can also use the UUID returned by POST /api/accounts.

TIP

Pro users get higher rate limits, custom domains, webhooks, and multi-account management — but the core email API is identical.

Step 1: Get Available Domains ​

bash
curl https://api.mail.td/api/domains
json
{
  "domains": [
    { "id": "...", "domain": "mail.td", "default": true, "sort_order": 0 },
    { "id": "...", "domain": "fexbox.org", "default": false, "sort_order": 1 }
  ]
}

Step 2: Create an Account ​

bash
curl -X POST https://api.mail.td/api/accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer td_xxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "address": "demo@mail.td",
    "password": "supersecret"
  }'
json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
  "address": "demo@mail.td"
}

INFO

Save the id (account ID). It is used as {account_id} in all subsequent API calls.

Step 3: Fetch Messages ​

Use the account ID to list and read emails. {account_id} accepts either the UUID or the email address:

bash
# List messages (using UUID)
curl https://api.mail.td/api/accounts/a1b2c3d4-e5f6-7890-abcd-1234567890ab/messages \
  -H "Authorization: Bearer td_xxxxxxxxxxxxxxxxxxxx"

# List messages (using email address)
curl https://api.mail.td/api/accounts/demo@mail.td/messages \
  -H "Authorization: Bearer td_xxxxxxxxxxxxxxxxxxxx"

# Read a specific message
curl https://api.mail.td/api/accounts/a1b2c3d4-e5f6-7890-abcd-1234567890ab/messages/f5e6d7c8-... \
  -H "Authorization: Bearer td_xxxxxxxxxxxxxxxxxxxx"
json
{
  "id": "f5e6d7c8-...",
  "sender": "noreply@example.com",
  "from": "Example <noreply@example.com>",
  "subject": "Verify your email",
  "address": "demo@mail.td",
  "size": 4523,
  "created_at": "2025-01-15T10:30:00Z",
  "text_body": "Click the link below to verify your email...",
  "html_body": "<html>...</html>",
  "attachments": []
}

That's it — three steps, zero setup.

Code Examples ​

Python ​

python
# Using the SDK (recommended):
from mailtd import MailTD

client = MailTD("td_xxxxxxxxxxxxxxxxxxxx")
account = client.accounts.create("demo@mail.td", password="supersecret")
messages, page = client.messages.list(account.id)
for msg in messages:
    detail = client.messages.get(account.id, msg.id)
    print(detail.subject, detail.text_body)
python
# Using raw HTTP:
import requests

API = "https://api.mail.td/api"
TOKEN = "td_xxxxxxxxxxxxxxxxxxxx"
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# 1. Create account
r = requests.post(f"{API}/accounts", json={
    "address": "demo@mail.td", "password": "supersecret",
}, headers=headers)
data = r.json()
account_id = data["id"]

# 2. Fetch messages
messages = requests.get(f"{API}/accounts/{account_id}/messages", headers=headers).json()

for msg in messages["messages"]:
    print(f"{msg['from']}: {msg['subject']}")
    detail = requests.get(
        f"{API}/accounts/{account_id}/messages/{msg['id']}", headers=headers
    ).json()
    print(detail["text_body"])

JavaScript (Node.js) ​

javascript
// Using the SDK (recommended):
import { MailTD } from 'mailtd';

const client = new MailTD('td_xxxxxxxxxxxxxxxxxxxx');
const account = await client.accounts.create('demo@mail.td', { password: 'supersecret' });
const { messages } = await client.messages.list(account.id);
for (const msg of messages) {
  const detail = await client.messages.get(account.id, msg.id);
  console.log(detail.subject, detail.text_body);
}
javascript
// Using raw HTTP:
const API = "https://api.mail.td/api";
const TOKEN = "td_xxxxxxxxxxxxxxxxxxxx";
const hdrs = { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json" };

// 1. Create account
let res = await fetch(`${API}/accounts`, {
  method: "POST",
  headers: hdrs,
  body: JSON.stringify({ address: "demo@mail.td", password: "supersecret" }),
});
const { id: accountId } = await res.json();

// 2. Fetch messages
const { messages } = await (
  await fetch(`${API}/accounts/${accountId}/messages`, { headers: hdrs })
).json();

for (const msg of messages) {
  console.log(`${msg.from}: ${msg.subject}`);
  const detail = await (
    await fetch(`${API}/accounts/${accountId}/messages/${msg.id}`, { headers: hdrs })
  ).json();
  console.log(detail.text_body);
}

What's Next? ​

Mail.td API Documentation