Send React Email templates.

Before you start

You need a verified sending domain (see Domains) and an API key (under API keys in the dashboard; it is shown once). Keep the key in an environment variable on your server, never in code that runs in a browser or an app.

1npm install mailtruss @react-email/components @react-email/render react

1import { Body, Button, Container, Heading, Html, Text } from "@react-email/components";
2import { render } from "@react-email/render";
3import { MailClient } from "mailtruss";
4​
5function Welcome({ name }: { name: string }) {
6  return (
7    <Html>
8      <Body style={{ fontFamily: "sans-serif" }}>
9        <Container>
10          <Heading>Welcome, {name}</Heading>
11          <Text>Your account is ready.</Text>
12          <Button
13            href="https://yourdomain.com/start"
14            style={{ background: "#533afd", color: "#fff", padding: "10px 16px" }}
15          >
16            Get started
17          </Button>
18        </Container>
19      </Body>
20    </Html>
21  );
22}
23​
24const mail = new MailClient({ apiKey: process.env.MAILTRUSS_API_KEY! });
25const element = <Welcome name="Ada" />;
26​
27export const sent = await mail.emails.send({
28  from: "Acme <hello@yourdomain.com>",
29  to: "delivered@mailtruss.test",
30  subject: "Welcome to Acme",
31  html: await render(element),
32  text: await render(element, { plainText: true }),
33});

Try it without sending real mail

Send to delivered@mailtruss.test first. It works before any domain is verified and reaches no real mailbox, so you can check your code and see the recorded timeline. Then try bounced@mailtruss.test to see what a bounce looks like. All the test addresses are listed under Sending.

See what happened

Open the message under Emails in the dashboard: it shows the recorded timeline, what each event proves, and a diagnosis if something went wrong. Or fetch it with GET /api/v1/emails/:id/events. To be told as it happens, add a webhook.

If it fails

API requests answer with an error name and message. The common ones:

• 403 invalid_api_key or 401 missing_api_key: the key is wrong, revoked or not sent. Send it as Authorization: Bearer ms_live_….
• 403 domain_not_verified: the from address is on a domain that is not verified. Publish the DNS records and re-check.
• 422 validation_error: fix the field the message names. Nothing was sent and no quota was used.
• 429 rate_limit_exceeded: back off for the Retry-After header. See rate limits.

Problems that happen after a message is accepted (bounces, complaints) are explained under delivery errors.

Other guides

• Next.js
• Express webhooks
• Supabase Auth
• Laravel
• Rails
• Django
• Nodemailer