Send email in Node.js.

Install

Get a key under API keys in the dashboard and verify a sending domain first (how). Then add the library:

1npm install mailtruss

Send an email

This sends one message and passes an idempotency key, so repeating the request can never deliver it twice. A send is retried only when you pass an idempotencyKey; reads and deletes retry on 429 and 5xx.

1import { MailClient } from "mailtruss";
2​
3const mail = new MailClient({ apiKey: process.env.MAILTRUSS_API_KEY! });
4​
5const { id } = await mail.emails.send(
6  { from: "Ada <ada@yourdomain.com>", to: "you@example.com", subject: "Hello", html: "<p>It works.</p>" },
7  { idempotencyKey: "order-42" }, // makes retries safe
8);

More on what you can put in a message (cc, bcc, attachments, tags, templates, scheduling) is under Sending.

Verify webhook signatures

Mailtruss signs every webhook with the Standard Webhooks scheme. Check the signature before you trust a request. Read the raw body with req.text(): re-serialised JSON will not match the signature.

1import { verifyWebhook } from "mailtruss";
2​
3export async function POST(req: Request) {
4  try {
5    const event = await verifyWebhook(await req.text(), req.headers, process.env.MAILTRUSS_WEBHOOK_SECRET!);
6    // event.type: "email.delivered", "email.bounced", ...
7    return new Response("ok");
8  } catch {
9    return new Response("invalid signature", { status: 400 });
10  }
11}

Events, payloads and retries are on the Webhooks page.

Handle errors

Failures throw MailError with statusCode, name_ and requestId. Search the request ID in the dashboard's API logs. Every error name, with its cause and fix, is in the error catalogue.

Other languages

• Python
• Go
• PHP
• Ruby
• Java
• .NET
• curl and HTTP