mailtd

Official Node.js SDK for Mail.td — the developer email platform for temp mail, email testing, and SMTP sandbox.

• Temp Mail API — Create and manage temporary email addresses programmatically
• Email Testing — Receive, inspect, and verify emails in your test suite
• SMTP Sandbox — Capture outbound emails in a safe sandbox environment without sending to real inboxes
• Webhooks — Get notified in real-time when emails arrive
• Custom Domains — Use your own domain for branded temporary mailboxes

Install

npm install mailtd

Requires Node.js 18+.

Quick Start

import { MailTD } from 'mailtd';

const client = new MailTD('td_...');

// Create a temporary email address
const account = await client.accounts.create('[email protected]', {
  password: 'mypassword',
});

// List messages
const { messages } = await client.messages.list(account.id);

// Get a message
const message = await client.messages.get(account.id, messages[0].id);
console.log(message.subject, message.text_body);

Use Cases

• Automated testing — Create temp mail addresses in CI/CD to test signup flows, OTP verification, and transactional emails
• Email verification testing — Validate that your app sends the right emails with the right content
• SMTP sandbox — Route your app's outbound SMTP to Mail.td sandbox to inspect emails without spamming real users
• QA environments — Give each test run its own mailbox, then tear it down

Authentication

All API calls require a Pro API Token (td_...). Pass it when creating the client:

// With a token string
const client = new MailTD('td_...');

// With options
const client = new MailTD({
  token: 'td_...',
  baseUrl: 'https://api.mail.td', // default
});

Resources

Accounts

// List available domains
const domains = await client.accounts.listDomains();

// Create a mailbox
const account = await client.accounts.create('[email protected]', {
  password: 'pass123',
});

// Get mailbox info
const info = await client.accounts.get(accountId);

// Reset password
await client.accounts.resetPassword(accountId, { password: 'newpass' });

// Delete a mailbox
await client.accounts.delete(accountId);

Messages

// List messages (30 per page)
const { messages, page } = await client.messages.list(accountId);
const page2 = await client.messages.list(accountId, { page: 2 });

// Get full message
const msg = await client.messages.get(accountId, messageId);

// Download raw EML
const eml = await client.messages.getSource(accountId, messageId);

// Download attachment
const file = await client.messages.getAttachment(accountId, messageId, 0);

// Mark as read
await client.messages.markAsRead(accountId, messageId);
await client.messages.batchMarkAsRead(accountId, { all: true });

// Delete
await client.messages.delete(accountId, messageId);

Domains (Pro)

const domains = await client.domains.list();
const result = await client.domains.create('example.com');
console.log(result.dns_records); // DNS records to configure
const status = await client.domains.verify(result.id);
await client.domains.delete(result.id);

Webhooks (Pro)

const webhook = await client.webhooks.create({
  url: 'https://example.com/webhook',
  events: ['email.received'],
});
console.log(webhook.secret); // whsec_...

const deliveries = await client.webhooks.listDeliveries(webhook.id);
const { secret } = await client.webhooks.rotateSecret(webhook.id);
await client.webhooks.delete(webhook.id);

Sandbox (Pro)

const info = await client.sandbox.getInfo();
console.log(`SMTP: ${info.smtp_host}:${info.smtp_port}`);

const { messages } = await client.sandbox.listMessages();
const msg = await client.sandbox.getMessage(messageId);
await client.sandbox.purgeMessages();

Tokens (Pro)

const { token } = await client.tokens.create('CI Token');
const tokens = await client.tokens.list();
await client.tokens.revoke(tokenId);

Billing (Pro)

const status = await client.billing.getStatus();
await client.billing.cancel();
await client.billing.resume();
const portalUrl = await client.billing.getPortalUrl();

User (Pro)

const me = await client.user.getMe();
const accounts = await client.user.listAccounts();
await client.user.deleteAccount(accountId);
await client.user.resetAccountPassword(accountId, { password: 'newpass' });
const { messages } = await client.user.listAccountMessages(accountId);

Error Handling

import { MailTD, APIError } from 'mailtd';

try {
  await client.accounts.create('[email protected]', { password: '...' });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status); // 409
    console.log(err.code);   // "address_taken"
  }
}

Links

• Website — Create temp mail, email testing, SMTP sandbox
• API Documentation — Full API reference
• Python SDK — pip install mailtd
• Go SDK — go get github.com/mailtd/mailtd-go
• CLI — Command-line tool

License

MIT