Skip to content

Documentation

Send Clerk emails through Mailtruss.

Clerk renders the email and hands it to your server. You send it with Mailtruss.

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.

How it works

Clerk has no SMTP settings screen. Each email template has a **Delivered by Clerk** switch. With it on, Clerk sends the email itself. With it off, Clerk still renders the email but does not send it: it posts the rendered message to your webhook, and you deliver it. The content, the codes and the sign-in logic stay in Clerk; only delivery moves to Mailtruss.

In the Clerk Dashboard

Turn the switch off for each template you want to send yourself, under Customization, then Emails. Then add a webhook endpoint on the Webhooks page, subscribe it to the email event, and copy its signing secret. Clerk's template page spells the event emails.created, but its SDK types and payloads call it email.created: pick the Email event in the dashboard's event list and the handler below checks for email.created. Set the secret as CLERK_WEBHOOK_SIGNING_SECRET.

Install

Clerk's backend package verifies the webhook. The Mailtruss client sends the email.

Terminal
npm install @clerk/backend mailtruss

The webhook handler

Clerk signs its webhooks, so the handler verifies the request first and answers 400 if it is not genuine. Clerk retries any webhook that does not get a 2xx, and a retry can reach you more than once, so the send uses the delivery's svix-id as an idempotency key: if the first attempt reached Mailtruss but your response never reached Clerk, the retry sends nothing twice. The from address must be on a domain you have verified in Mailtruss, not Clerk's.

app/api/webhooks/clerk/route.ts
import { verifyWebhook } from "@clerk/backend/webhooks";
import { MailClient, MailError } from "mailtruss";
​
const mail = new MailClient({ apiKey: process.env.MAILTRUSS_API_KEY! });
​
export async function POST(request: Request) {
// Reads CLERK_WEBHOOK_SIGNING_SECRET and checks the signature on the raw body.
let evt;
try { evt = await verifyWebhook(request); } catch { return new Response("Invalid signature", { status: 400 }); }
​
if (evt.type !== "email.created") return new Response("ignored", { status: 200 });
const email = evt.data;
// If Clerk is still delivering this template itself, sending here would send it twice.
if (email.delivered_by_clerk || !email.to_email_address || !email.subject || !email.body) return new Response("nothing to send", { status: 200 });
​
try {
await mail.emails.send(
{
from: "Acme <login@yourdomain.com>",
to: email.to_email_address,
subject: email.subject,
html: email.body, // Clerk's rendered HTML
text: email.body_plain ?? undefined, // and its plain-text version
},
{ idempotencyKey: `clerk:${request.headers.get("svix-id") ?? email.id}` },
);
return new Response("ok", { status: 200 });
} catch (e) {
// 429 and 5xx are worth retrying (Clerk will); anything else will fail the same way again.
if (e instanceof MailError && (e.statusCode === 429 || e.statusCode >= 500)) return new Response("try again", { status: 503 });
console.error("clerk email not sent", e instanceof MailError ? { code: e.code, requestId: e.requestId } : e);
return new Response("not sent", { status: 200 });
}
}

What Clerk sends

The event's data carries to_email_address, subject, body (the rendered HTML), body_plain, slug (which template it is, such as a verification code or a magic link), data (the template's variables, such as the one-time code), user_id and delivered_by_clerk. These are the fields in Clerk's own SDK types. Log one real event while you set up and check the shape, but do not keep one-time codes in your logs.

Leave tracking off for sign-in links

Mailtruss's click tracking rewrites links, which you do not want on a magic link or a one-time code. Tracking is off by default per domain: leave it off for the domain you use for Clerk, or switch it off for these messages.

Try it without sending real mail

Clerk's webhook page lists every delivery under Message attempts, with the response your handler gave and the raw payload, and can replay a message. Trigger one real sign-in with a test user, then open the message under Emails in the Mailtruss dashboard.

Check the latest message
curl -s "https://mailtruss.com/api/v1/emails?limit=1" -H "Authorization: Bearer $MAILTRUSS_API_KEY"

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

Last updated

Something wrong or unclear on this page?

Report an issue