Email deliverability

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(opens in a new tab) using a pool of dedicated IP addresses to ensure that our reputation stays perfect.

In development instances, all emails are sent from @accounts.dev domain. In production instances, they are sent from your own domain e.g. @example.com.

During production instance set up, Clerk will have you set SPF, DKIM, and mail records. There are a few additional things you should set up to ensure maximum deliverability.

Best practices

Following the practices below will allow emails to be delivered quickly and reliably:

• Refrain from sending any spam from your domain
• Set up an inbox for your domain's "from" address
• Try sending email verification codes instead of verification links
• Use Clerk's default emails
• Make sure DMARC is set up

Deliverability factors

Email deliverability is made of a number of factors, each contributing to whether or not it will get classified as spam, quarantined, or delayed.

IP address reputation and blocklists

Email providers check against a pool of IP addresses and domain blocklists 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.

Domain name reputation

Every domain name (i.e. example.com, clerk.com, etc.) has its own reputation score. Newer domains do not have a high score, and this may impact deliverability.

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 notifications@yourdomain.com. You should make sure that you set up a mailbox at this email address. If you'd like to use a different "from address", you can change its value via our Backend API(opens in a new tab).

Email content

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.

Email traps

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".

Setup 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. The following is an example DMARC policy that Clerk uses for its own emails.

TXT Record

name:
_dmarc<.example.com>

content:
v=DMARC1; p=reject; pct=100; rua=mailto:you@example.com; ruf=mailto:you@example.com;

This policy will reject all emails that weren't sent from you. There are other policies(opens in a new tab) that you can use.

Known provider-related issues

Despite all precautions, emails still sometimes end up in spam or quarantined. It's worth noting that if you're running into these issues, it's likely not a unique situation. 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. While the following provider-related issues are common, following the steps listed at the top of this document is very likely to get your emails delivered to these inboxes. The two main culprits we've run into are as follows.

Gmail

The most common issue with Clerk's verification emails is that they are "delayed" for roughly 4 minutes. This only happens with email addresses that are part of Google Workspace due to their "pre-delivery message scanning."(opens in a new tab) To further debug email issues with Gmail, you should sign up for Gmail's postmaster tools(opens in a new tab).

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 the 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 email links, since they tend to have better deliverability with Outlook.

Another thing you can do is sign up for Sender Support(opens in a new tab), and make sure you're following all of their best practices.

Managing your own email delivery

In case you would like to manage Email and/or SMS delivery on your own, you can opt-out of delivery by Clerk, by toggling the "Send by Clerk" toggle in the dashboard.

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 this message, you will need to enable webhooks and listen for the email.created or 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.

Last updated on January 8, 2024