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('tm_pro_...');

// 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("tm_pro_...")

# 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("tm_pro_...")
ctx := context.Background()

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

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

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

Authentication

All SDKs accept a token in the constructor:

Token Type	Example	Usage
Mailbox JWT	eyJhbG...	Per-mailbox access (from accounts.create() or accounts.login())
Pro API Token	tm_pro_...	Full Pro access (recommended for server-to-server)

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

account, err := client.Accounts.Create(ctx, "taken@mail.td", &mailtd.CreateAccountOpts{Password: "..."})
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	Description
accounts	Mailbox creation, login, account info
messages	List, get, delete, attachments, mark as read
domains	Custom domain management (Pro)
webhooks	Webhook CRUD and delivery history (Pro)
tokens	API token management (Pro)
sandbox	SMTP sandbox messages (Pro)
billing	Subscription status and management (Pro)
user	Pro user profile and multi-account management

Full API reference for each resource is available in the GitHub README of each SDK.