If you are having email issues, make sure you're following all of the best practices outlined in this document.
A lot goes into making sure verification emails make it to your customers as quickly as possible. Clerk uses every best practice, and is proactive about monitoring verification email deliverability and speed. Behind the scenes, Clerk uses Sendgrid using a pool of dedicated IP addresses to ensure that our reputation stays perfect.
Every email provider has a different set of rules which classify emails as spam. The Clerk team is constantly reviewing these rules, and any changes to them, to make sure all emails reach your customer's inboxes as fast as possible. Because Clerk only sends verification emails, our deliverability is often better than what you would be able to achieve on your own using email services.
In development instances, all emails are sent from
@lcl.dev domain. In production instances, they are sent from your own domain e.g.
During production, instance setup Clerk will have you set SPF, DKIM, and mail records. There are a few additional things you should setup to ensure maximum deliverability.
Setup DMARC email authentication
DMARC, or "Domain-based Message Authentication, Reporting & Conformance", should also be setup on your domain. If an email ever fails one of the above checks, email providers will act based on the settings you choose here. In order to setup a DMARC policy, you will need to add a TXT record to your domain. The following is an example DMARC policy that Clerk uses for its own emails.
This policy will reject all emails that weren't sent from you. There are other policies that you can use.
Setup a real email address
Email providers will check if there's an actual mailbox behind the "from address" of an email. By default, Clerk will send your emails from
email@example.com. You should make sure that you set up a mailbox at this email address. Or. if you'd like to use a different "from address", you can change its value via our Backend API.
Email deliverability is made of a number of factors, each contributing to whether or not it will get classified as spam, quarantined, or delayed. Some of these are in Clerk's control, others are steps that you should take to ensure the best deliverability possible.
IP Address Reputation
Clerk is using a dedicated IP Address, pooled amongst all of our customers, sending millions of verification emails monthly. This gives our IP Address a near-perfect reputation, with basically 0 spam reports on its record, or other issues common to other pooled services.
If you need your own dedicated IP pool, talk to us to set it for you.
Domain name reputation
Every domain name (i.e. example.com, clerk.dev, etc.) has its own reputation score. Newer domains do not have a high score, and this may impact deliverability.
We rolled out an experimental email mode which will send your OTP verification emails via the clerk.dev domain, as a potential workaround for domain reputation issues. If you're interested in trying it out, let us know.
The email content is scanned by email providers, so this also plays a crucial role in determining if an email clears spam filters. Clerk's default verification email copy is optimized based on trial and error, so, make modifications to the default template at your own risk. However, minor changes are usually ok.
SPF and DKIM email authentication
These records are set up during production instance initialization and tell email providers which servers and domains are authorized to send emails on behalf of your organization. They also add a digital signature to every outgoing message, which lets providers verify that emails were indeed sent from you. Almost all email providers look for these to be set as a strong signal of legitimacy. Clerk handles these records for you automatically.
DMARC email authentication
DMARC, or "Domain-based Message Authentication, Reporting & Conformance", should also be set up on your domain. If an email ever fails one of the above checks, email providers will act based on the settings you choose here. In order to set up a DMARC policy, you will need to add a TXT record to your domain.
Sending from a real email address
By default, Clerk will send your emails from "firstname.lastname@example.org". Email providers will check if there's an actual mailbox behind this email address, so you should make sure that you set up a mailbox for this email address.
IP address and domain blacklists
Email providers check against a pool of IP addresses and domain blacklists to protect against bad actors. Clerk is constantly monitoring to make sure our IP addresses are not on any of these lists. If you're experiencing issues, it may be helpful to verify that your domain doesn't live on any of these lists.
Because a lot of bad actors send spam to large programmatically generated lists, mailbox providers have set up "email traps". If you send to one of these trap email addresses, it will get you flagged, and heavily ding your domain or IP address. Because we only send verification emails, it is very unlikely that Clerk will fall into one of these traps. Out of necessity mailbox providers do not advertise which addresses are "traps".
Despite all precautions, emails still sometimes end up in spam or quarantined. Trying to figure out what is going wrong is a painful process, and some email providers are notoriously opaque and overly aggressive with their spam filters. This is always frustrating, especially when it comes to verification emails. The two main culprits we've run into are as follows.
The most common issue with Clerk's verification emails is that are "delayed" for roughly 4 minutes. This only happens with email addresses that are part of Google Workspace, and it's due to their "pre-delivery message scanning." To further debug email issues with gmail, you should sign up for GMails postmaster tools.
Microsoft (Hotmail / Outlook / Office365)
Microsoft Defender's aggressive anti-spam filters are the most common reason that verification emails might not reach certain Outlook inboxes.
In an event that an email does not reach an Outlook recipient at all, this most likely means they are placed in Quarantine and the workspace's administrator has been able to restore it. If you encounter this issue, try switching to OTP codes instead of magic links, since they tend to have better deliverability with Outlook.
Another thing you can do is sign up for Sender Support, and make sure you're following all of their best practices.
Managing your own Email & SMS delivery
In case you would like to manage Email and/or SMS delivery on your own, you can opt-out of delivery by Clerk, as documented in the Email & SMS templates section.
When toggled off, emails or SMS messages based on the affected template will not be delivered to the end user by Clerk. In order to handle the delivery of the said message, you will need to enable webhooks and listen to the
sms.created events, respectively.
The event contains both the original message that Clerk would send, in case you would like to use it as-is , or the necessary metadata for you to create messages with your own copywriting. For instance, for a verification code email the
email.created event will contain the
otp_code, which you can then use in your own messaging.
Note: This setting is per email & SMS (template), i.e. not global.
Emails are tricky business, and not foolproof. It is very tough to get to 100% deliverability, which is frustrating to hear. With Clerk, you get a team monitoring deliverability of your verification emails to make this part of application development easier for you.