SDKs

Official client libraries for the Mail.td API. All SDKs cover the full API surface with typed responses and error handling.

Available SDKs

Node.js / TypeScript
npm install mailtd
Zero dependencies, native fetch, full type definitionsPython
pip install mailtd
httpx-based, dataclass types, context manager supportGo
go get github.com/mailtd/mailtd-go
net/http, context-based, full struct types

Quick Start

Node.js

import { MailTD } from 'mailtd';

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

// Create a mailbox
const account = await client.accounts.create('test@mail.td', {
  password: 'mypassword',
});

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

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

Python

from mailtd import MailTD

client = MailTD("td_...")

# Create a mailbox
account = client.accounts.create("test@mail.td", password="mypassword")

# List messages
messages, page = client.messages.list(account.id)

# Get a message
msg = client.messages.get(account.id, messages[0].id)
print(msg.subject, msg.text_body)

Go

client := mailtd.NewClient("td_...")
ctx := context.Background()

// Create a mailbox
pw := "mypassword"
account, _ := client.Accounts.Create(ctx, "test@mail.td", &mailtd.CreateOptions{
    Password: &pw,
})

// List messages
result, _ := client.Messages.List(ctx, account.ID, nil)

// Get a message
msg, _ := client.Messages.Get(ctx, account.ID, result.Data[0].ID)
fmt.Println(msg.Subject, *msg.TextBody)

Authentication

All SDKs accept a Pro API Token in the constructor:

Node.js

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

// Custom base URL (optional)
const client = new MailTD({ token: 'td_...', baseUrl: 'https://custom.api.url' });

Python

client = MailTD("td_...")

# Custom base URL (optional)
client = MailTD("td_...", base_url="https://custom.api.url")

# Context manager support
with MailTD("td_...") as client:
    ...

Go

client := mailtd.NewClient("td_...")

// Custom base URL (optional)
client := mailtd.NewClient("td_...", mailtd.WithBaseURL("https://custom.api.url"))

Error Handling

All SDKs throw/raise an APIError with status (HTTP code) and code (error string):

Node.js

import { MailTD, APIError } from 'mailtd';

try {
  await client.accounts.create('taken@mail.td', { password: '...' });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status); // 409
    console.log(err.code);   // "address_taken"
  }
}

Python

from mailtd import MailTD, APIError

try:
    client.accounts.create("taken@mail.td", password="...")
except APIError as e:
    print(e.status)  # 409
    print(e.code)    # "address_taken"

Go

pw := "..."
account, err := client.Accounts.Create(ctx, "taken@mail.td", &mailtd.CreateOptions{
    Password: &pw,
})
if err != nil {
    var apiErr *mailtd.APIError
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.Status) // 409
        fmt.Println(apiErr.Code)   // "address_taken"
    }
}

Resources

Each SDK exposes the same resource structure:

Resource	Methods	Description
accounts	create, get, delete, resetPassword, listDomains	Mailbox management and domain listing
messages	list, get, delete, getSource, getAttachment, markAsRead, batchMarkAsRead	Email operations
domains	list, create, verify, delete	Custom domain management (Pro)
webhooks	list, create, delete, rotateSecret, listDeliveries	Webhook management (Pro)
tokens	list, create, revoke	API token management (Pro)
billing	getStatus, cancel, resume, getPortalUrl	Subscription management (Pro)
user	getMe, listAccounts, deleteAccount, resetAccountPassword, listAccountMessages	Pro user profile and multi-account management

Common Patterns

Polling for new messages

Node.js

// Poll every 10 seconds until an email arrives
async function waitForEmail(client, accountId, timeout = 60000) {
  const start = Date.now();
  while (Date.now() - start < timeout) {
    const { messages } = await client.messages.list(accountId);
    if (messages.length > 0) return messages[0];
    await new Promise(r => setTimeout(r, 10000));
  }
  throw new Error('Timeout waiting for email');
}

Python

import time

def wait_for_email(client, account_id, timeout=60):
    start = time.time()
    while time.time() - start < timeout:
        messages, _ = client.messages.list(account_id)
        if messages:
            return messages[0]
        time.sleep(10)
    raise TimeoutError("Timeout waiting for email")

Go

func waitForEmail(ctx context.Context, client *mailtd.Client, accountID string, timeout time.Duration) (*mailtd.EmailSummary, error) {
    deadline := time.Now().Add(timeout)
    for time.Now().Before(deadline) {
        result, err := client.Messages.List(ctx, accountID, nil)
        if err != nil {
            return nil, err
        }
        if len(result.Data) > 0 {
            return &result.Data[0], nil
        }
        time.Sleep(10 * time.Second)
    }
    return nil, fmt.Errorf("timeout waiting for email")
}

Download attachments

Node.js

const msg = await client.messages.get(accountId, messageId);
for (const att of msg.attachments) {
  const data = await client.messages.getAttachment(accountId, messageId, att.index);
  // data is ArrayBuffer
  fs.writeFileSync(att.filename, Buffer.from(data));
}

Python

msg = client.messages.get(account_id, message_id)
for att in msg.attachments:
    data = client.messages.get_attachment(account_id, message_id, att.index)
    with open(att.filename, "wb") as f:
        f.write(data)

Go

msg, _ := client.Messages.Get(ctx, accountID, messageID)
for _, att := range msg.Attachments {
    data, _ := client.Messages.GetAttachment(ctx, accountID, messageID, att.Index)
    os.WriteFile(att.Filename, data, 0644)
}