SDKs

Official libraries for Node.js and Python with typed results, retries and idempotency built in.

Install

There are official SDKs for Node.js (and TypeScript) and for Python. Both live in the MailForge repository under packages/.

# inside the MailForge repository
npm --workspace=@mailforge/node run build

# inside your project
npm install /path/to/mailforge/packages/sdk-node

The Node.js SDK needs Node 18.17 or newer and has no runtime dependencies. The Python SDK needs Python 3.9 or newer and uses httpx.

Send an email

Pass your API key and the URL of your MailForge server. Both can also come from the environment variables MAILFORGE_API_KEY and MAILFORGE_BASE_URL.

import { Mailforge } from "@mailforge/node";

const mailforge = new Mailforge(process.env.MAILFORGE_API_KEY, {
  baseUrl: "https://mail.example.com"
});

const { data, error } = await mailforge.emails.send({
  from: "Acme <hello@acme.com>",
  to: "customer@example.com",
  subject: "Welcome to Acme",
  html: "<p>Your account is ready.</p>"
});

if (error) {
  console.error(error.code, error.message);
} else {
  console.log(data.id);
}

In Python, from_ has an underscore because from is a reserved word. The Python SDK also has an AsyncMailforge client with the same methods.

Errors

The Node.js SDK never throws. Every method resolves to { data, error }, and exactly one of the two is null. The Python SDK raises a subclass of MailforgeError.

const { data, error } = await mailforge.emails.send({
  from: "hello@acme.com",
  to: "not-an-address",
  subject: "Hi",
  text: "Hello"
});

if (error) {
  console.log(error.code);       // "validation_error"
  console.log(error.statusCode); // 422
  console.log(error.details);    // { to: ["Invalid email address"] }
}
CodePython exceptionWhen
validation_errorValidationError422, or a missing field caught before the request
unauthorizedAuthenticationError401, wrong or revoked key
forbiddenPermissionDeniedError403, key lacks the permission
not_foundNotFoundError404
conflictConflictError409
rate_limitedRateLimitError429 after all retries
server_errorServerError5xx after all retries
network_errorAPIConnectionErrorNo response
timeoutAPITimeoutErrorNo response in time

Retries and idempotency

Requests are retried up to 2 times with exponential backoff on network errors, 429 and 5xx. Every send carries an idempotency key, generated for you when you do not pass one, so a retry cannot deliver the same email twice. Pass your own key to make a send repeatable across process restarts.

await mailforge.emails.send(email, {
  idempotencyKey: `order-${order.id}-receipt`
});

// Client-wide settings
new Mailforge(key, { baseUrl, timeout: 10_000, maxRetries: 5 });

React Email

In Node.js you can pass a React element as react. The SDK renders it to HTML and a plain-text alternative. This needs @react-email/render in your project. If a component throws while rendering, you get a render_error and nothing is sent.

Terminal
npm install @react-email/render @react-email/components
welcome.tsx
import { Button, Html } from "@react-email/components";

function WelcomeEmail({ name }: { name: string }) {
  return (
    <Html>
      <h1>Welcome, {name}!</h1>
      <Button href="https://acme.com/start">Get started</Button>
    </Html>
  );
}

await mailforge.emails.send({
  from: "Acme <hello@acme.com>",
  to: "customer@example.com",
  subject: "Welcome",
  react: <WelcomeEmail name="Ada" />
});

Batch sending

batch.send sends a list of emails as parallel single requests. One failing email does not stop the others, so a batch is not all-or-nothing. Check the result of each item. For one atomic request with up to 100 emails, call the batch endpoint directly.

const { data } = await mailforge.batch.send(
  users.map((user) => ({
    from: "Acme <hello@acme.com>",
    to: user.email,
    subject: "Your weekly summary",
    text: `Hi ${user.name}, here is your summary.`
  })),
  { concurrency: 10 }
);

console.log(data.sent, data.failed);

What the SDKs cover

AreaNode.jsPython
Emailsemails.send, emails.list, batch.sendemails.send, emails.list, batch.send
Templatestemplates.create, list, get, update, remove, render, sendtemplates.create, list, get, update, remove, render, send
Domainsdomains.create, list, verifydomains.create, list, verify
API keysapiKeys.create, list, removeapi_keys.create, list, remove
Providersproviders.create, listproviders.create, list
Inboundinbound.list, webhooks.verifyinbound.list, webhooks.verify
Automationsautomations.create, listautomations.create, list

Not wrapped by the SDKs yet: the analytics endpoints, the webhooks and suppressions endpoints, reading a single email and canceling a scheduled one. Use plain HTTP for those. Call them over HTTP.