Sandbox API

Query, inspect, and manage emails captured by the SMTP Sandbox. All endpoints require a Pro API token in the Authorization header.

Authorization: Bearer td_your_token_here

Get Sandbox Status

Returns SMTP credentials and usage information.

GET /api/user/sandbox

Response

{
  "enabled": true,
  "account_id": "a1b2c3d4-...",
  "address": "sandbox-a1b2c3d4@sandbox.mail.td",
  "smtp_host": "smtp.mail.td",
  "smtp_port": 587,
  "auth_method": "PLAIN",
  "username": "any",
  "note": "Use any API token as the SMTP password",
  "quota": 104857600,
  "used": 2457600
}

Field	Description
enabled	true if sandbox account exists (created on first SMTP connection)
smtp_port	Default SMTP port. Ports 587, 25, 465, and 2525 are all supported
quota	Storage limit in bytes (100 MB)
used	Current usage in bytes

---

List Captured Emails

Returns emails in the sandbox inbox, newest first.

GET /api/user/sandbox/messages?page=1

Parameters

Name	Type	Description
page	query, optional	Page number (default: 1, 30 per page)

Response

{
  "messages": [
    {
      "id": "e5f6g7h8-...",
      "sender": "noreply@yourapp.com",
      "from": "YourApp <noreply@yourapp.com>",
      "subject": "Welcome to YourApp",
      "preview_text": "Thanks for signing up! Click the link below to...",
      "size": 4521,
      "is_read": false,
      "created_at": "2025-03-15T10:30:00Z"
    }
  ],
  "page": 1
}

---

Get Email Detail

Returns the full content of a captured email, including HTML body, plain text, attachments, and email authentication results.

GET /api/user/sandbox/messages/:id

Response

{
  "id": "e5f6g7h8-...",
  "sender": "noreply@yourapp.com",
  "from": "YourApp <noreply@yourapp.com>",
  "subject": "Welcome to YourApp",
  "address": "user@example.com",
  "size": 4521,
  "created_at": "2025-03-15T10:30:00Z",
  "text_body": "Thanks for signing up!\n\nClick the link below...",
  "html_body": "<h1>Welcome!</h1><p>Thanks for signing up!</p>...",
  "attachments": [
    {
      "index": 0,
      "filename": "invoice.pdf",
      "size": 12800,
      "content_type": "application/pdf"
    }
  ],
  "auth_results": {
    "spf": "pass",
    "dkim": "pass",
    "dmarc": "pass"
  }
}

Field	Description
text_body	Plain text version of the email
html_body	HTML version (may be empty if text-only)
attachments	List of attachments with index for download
auth_results	SPF, DKIM, and DMARC verification results

Authentication results

The auth_results object contains the verification status for each email authentication method:

Field	Values	Description
spf	pass, fail, softfail, neutral, none, temperror, permerror	SPF verification against the sender's IP
dkim	pass, fail, none, temperror, permerror	DKIM signature verification
dmarc	pass, fail, none	DMARC policy alignment check

TIP

Use auth_results in your CI tests to verify that your email sending infrastructure has correct SPF, DKIM, and DMARC configuration before deploying to production.

---

Download Raw Source

Downloads the original .eml file. The Authentication-Results header is prepended with SPF/DKIM/DMARC results.

GET /api/user/sandbox/messages/:id/source

Response: message/rfc822 binary with Content-Disposition: attachment; filename="message.eml"

---

Download Attachment

Downloads a specific attachment by index.

GET /api/user/sandbox/messages/:id/attachments/:index

Response: Binary file with appropriate Content-Type and Content-Disposition headers.

---

Delete a Single Email

DELETE /api/user/sandbox/messages/:id

Response

{
  "deleted": true
}

INFO

Deleting an email reclaims its storage quota immediately.

---

Purge All Emails

Deletes all emails in the sandbox and resets the usage counter.

DELETE /api/user/sandbox/messages

Response

{
  "deleted": 42
}

---

Errors

Status	Error Code	Description
401	invalid_or_expired_token	Missing or invalid API token
402	subscription_expired	Pro subscription is not active
404	sandbox_not_found	No sandbox account exists yet (send an email first)
404	email_not_found	Email ID does not exist or has expired
404	attachment_not_found	Invalid attachment index
410	email_expired	Email source file has been cleaned up

---

Example: Automated Test (Node.js)

const assert = require("assert");

const API = "https://api.mail.td/api/user";
const TOKEN = process.env.MAILTD_TOKEN;

async function fetchSandboxMessages() {
  const res = await fetch(`${API}/sandbox/messages`, {
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  return res.json();
}

// After your app sends an email...
const { messages } = await fetchSandboxMessages();
const latest = messages[0];

assert(latest.subject.includes("Welcome"));
assert(latest.from.includes("yourapp.com"));

// Get full content and verify authentication
const detail = await fetch(`${API}/sandbox/messages/${latest.id}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
}).then(r => r.json());

assert(detail.html_body.includes("verify your email"));
assert.equal(detail.auth_results.spf, "pass");
assert.equal(detail.auth_results.dkim, "pass");
assert.equal(detail.auth_results.dmarc, "pass");
console.log("Email test passed!");