Email delivery
Best practices for sending email with WorkOS.
Many WorkOS features rely on your users receiving and acting upon email. For example, this includes invitations to join your app, password reset links, or Magic Auth sign-in. Prompt delivery of these emails is crucial.
WorkOS offers three options for sending email:
- WorkOS email domain: WorkOS sends email from the
workos-mail.comdomain. - Your email domain: WorkOS sends email from your own email domain.
- Send your own email: WorkOS emits events, allowing your app to listen to these events and send email using your own email provider.
These options provide different trade-offs between convenience, customization, and control over email deliverability.
WorkOS follows industry best practices when sending email. SPF and DKIM email authentication records are configured automatically, the email content is continually refined to ensure it passes spam filters, and delivery of every email is actively monitored. However, regardless of the option you chose for sending email to your users, there are additional steps you can take to ensure that it reaches user inboxes.
By default WorkOS will send the following emails from the workos-mail.com domain in production environments.
WorkOS has configured SPF, DKIM and DMARC email authentication records for the workos-mail.com domain. These records prove to the receiving mail server that a given email comes from WorkOS.
We actively monitor the delivery of email sent from the workos-mail.com domain to protect the domain’s reputation. If we detect unusually high rates of undelivered mail or mail marked as spam from a WorkOS team account, we may suspend that team’s ability to send email.
To ensure email is delivered when using the WorkOS email domain, be sure not to allow unsolicited email to be sent on your behalf. For example, an invitation email should be sent only if a user explicitly requests access to your application for themselves or another user. Do not attempt to bulk invite users from an email marketing list.
It is also important to ensure that your WorkOS team account and all organizations under your team have appropriate names that avoid common spam words that may trigger spam filters. While our static email content is thoroughly tested, WorkOS emails can include your team name as well as the names of organizations under your team. There may be an impact to email deliverability if these names use terms often flagged by spam filters.
While using the WorkOS email domain option is convenient, you can provide your users a better experience. Using your own email domain means that your users will receive emails from a domain they recognize, one associated with your app. In addition, because you control the email domain, you have more control over the domain reputation and therefore more control over email deliverability.
You can configure your own email domain in the WorkOS dashboard. You will need to verify ownership of the domain by setting up a CNAME record with your domain provider. Two additional CNAME records are required to automatically configure SPF and DKIM email authentication using Sendgrid’s automated security feature.
In addition to not sending unsolicited emails and using appropriate team and organization names, when using your own email domain there are a few additional steps you can take to ensure email is delivered promptly.
When using your own domain, email will be sent from welcome@<your domain> and access@<your domain>. Email providers check if there are inboxes associated with sender addresses, so setting up inboxes for both the welcome and access email addresses on your domain can help ensure your emails reach users.
WorkOS recommends that you set up DMARC (Domain-based Message Authentication, Reporting & Conformance) with your domain provider. Google has released guidelines for email senders and the guidelines include DMARC requirements. Apple and Yahoo have released similar best practice guides.
A DMARC policy tells a receiving mail server what to do when a message from your domain doesn’t pass DMARC authentication. Configuring DMARC requires setting up a DNS TXT record with your domain provider.
Here is an example DMARC record that will reject all emails not legitimately sent by an email provider on your behalf:
More details about DMARC can be found at dmarc.org.
There are a number of reasons why you may want to send email using your own email provider. Perhaps you already send a welcome email to new users and want to include an invitation link instead of sending a second email. Perhaps you want to translate the email text into different languages. Perhaps you already track sent email status with your own email provider and want a unified view into the status of all emails associated with your app. Regardless, when you send your own email, you have complete control over email deliverability.
For complete instructions on sending your own email, see the section on custom emails in the user management documentation.
When sending your own email, you will want to follow the all of the recommendations in Google’s email sender guidelines. This includes setting up SPF, DKIM and DMARC email authentication.
You will also need to be conscious of your sender reputation. It’s based on the quality of emails, their frequency, and user interaction. A good sender reputation can increase the chances of your emails reaching inboxes. Sendgrid provides some useful tips for improving sender reputation.
If you author your own email content, you may want to test your emails against various email providers’ spam filters. There are a number of spam testing services available such as Litmus and Warmly.
Even when following industry best practices, an email may get filtered as spam and not reach a user’s inbox. Other times an email might be delayed, for example, when Enhanced Pre-delivery Message Scanning is enabled on a Google workspace or when a similar feature is enabled with other email providers. Email providers do not explain the heuristics used by their spam filters and security mechanisms, and they are often changing, making it especially frustrating to troubleshoot problems.
The first step in troubleshooting is to determine if the problem exists for all users or only a subset of users. Generally, this will provide insight into the nature of the issue and how best to resolve it. If the issue exists for all users, it is most likely a matter of poor domain reputation. If the issue only exists for a subset of users, it may be because of specific settings used by an email provider or the IT department at a given organization.
Both Google and Microsoft have been noted as being especially aggressive when identifying spam. However, both companies provide some tooling to help you debug email deliverability problems. Google offers Postmaster Tools to help with email deliverability related to Gmail and Google Workspaces. Microsoft offers similar tools with Sender Support. Lastly, more general spam testing services such as Litmus and Warmly are available.
If you continue to have issues regarding email deliverability despite following all of the above suggestions, please contact support.