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.
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.
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.
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_keyor401 missing_api_key: the key is wrong, revoked or not sent. Send it asAuthorization: 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 theRetry-Afterheader. See rate limits.
Problems that happen after a message is accepted (bounces, complaints) are explained under delivery errors.