SDKs

Official libraries for Node.js and Python. Both have no dependencies, raise typed errors with the API’s error code, and only retry requests that are safe to repeat.

The SDKs are not on npm or PyPI yet. Install them from the Mailfy repository (packages/sdk-node and sdks/python) until they are published.

Node.js

Node 18.17 or newer (uses the built-in fetch).

TypeScript

import { Mailfy, MailfyError } from '@mailfy/node';

const mailfy = new Mailfy(process.env.MAILFY_API_KEY!);

try {
  const { id } = await mailfy.emails.send(
    { from: 'Acme <hi@acme.com>', to: 'ada@example.com', subject: 'Welcome', html: '<p>Hi!</p>' },
    { idempotencyKey: `welcome-${userId}` },
  );
} catch (err) {
  if (err instanceof MailfyError && err.code === 'QUOTA_EXCEEDED') {
    // back off until the next period
  }
  throw err;
}

await mailfy.events.track({ email: 'ada@example.com', event: 'signed_up', properties: { plan: 'pro' } });

Also available: emails.sendBatch, emails.get, emails.list, emails.cancel and verifyWebhook. Rate-limited (429) and server errors are retried automatically for reads and for writes with an idempotency key.

Python

Python 3.9 or newer, standard library only.

Python

from mailfy import Mailfy, MailfyError

mailfy = Mailfy(os.environ["MAILFY_API_KEY"])
try:
    result = mailfy.emails.send(
        {"from": "Acme <hi@acme.com>", "to": "ada@example.com", "subject": "Welcome", "html": "<p>Hi!</p>"},
        idempotency_key=f"welcome-{user_id}",
    )
except MailfyError as e:
    print(e.status, e.code, e.message, e.request_id)

mailfy.events.track("ada@example.com", "signed_up", {"plan": "pro"})