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-nodeThe 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"] }
}| Code | Python exception | When |
|---|---|---|
validation_error | ValidationError | 422, or a missing field caught before the request |
unauthorized | AuthenticationError | 401, wrong or revoked key |
forbidden | PermissionDeniedError | 403, key lacks the permission |
not_found | NotFoundError | 404 |
conflict | ConflictError | 409 |
rate_limited | RateLimitError | 429 after all retries |
server_error | ServerError | 5xx after all retries |
network_error | APIConnectionError | No response |
timeout | APITimeoutError | No 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.
npm install @react-email/render @react-email/componentsimport { 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
| Area | Node.js | Python |
|---|---|---|
| Emails | emails.send, emails.list, batch.send | emails.send, emails.list, batch.send |
| Templates | templates.create, list, get, update, remove, render, send | templates.create, list, get, update, remove, render, send |
| Domains | domains.create, list, verify | domains.create, list, verify |
| API keys | apiKeys.create, list, remove | api_keys.create, list, remove |
| Providers | providers.create, list | providers.create, list |
| Inbound | inbound.list, webhooks.verify | inbound.list, webhooks.verify |
| Automations | automations.create, list | automations.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.