Custom Email Providers

By default, WorkOS will send emails via our default email service provider, either through our domain or through your own custom email domain. If you would like to have more control over deliverability, reputation, and compliance, while still offloading the heavy lifting of email handling, you can configure a custom email provider. This option is also ideal if you already have an existing email service provider configuration.

To configure a custom email provider for an environment, navigate to Emails → Providers and click Enable next to the provider you would like to use and enter the required information.

To connect WorkOS to Amazon SES, you’ll need to create an IAM user with an access key, and verify email sending identities. Ensure the IAM user has a policy like the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "SendEmailAccess",
      "Effect": "Allow",
      "Action": "ses:SendEmail",
      "Resource": [
        "arn:aws:ses:<region>:<accountId>:identity/*",
        "arn:aws:ses:<region>:<accountId>:configuration-set/*"
      ]
    },
    {
      "Sid": "IdentityManagementAccess",
      "Effect": "Allow",
      "Action": ["ses:GetIdentityVerificationAttributes", "ses:ListIdentities"],
      "Resource": "*"
    }
  ]
}

You’ll need to update the resource scope with your Amazon SES region and account ID. For additional ways to restrict access, refer to the Amazon SES documentation.

Once you have an IAM user with the necessary permissions and have verified sending identities, you can configure the Amazon SES custom email provider in the WorkOS Dashboard:

Before configuring the Postmark custom email provider in WorkOS, you’ll need to verify sender signatures in your Postmark account.

Once you’ve verified a sender signature, you’ll need an account and server token, which you can find on the API Tokens page of the Postmark Dashboard.

The account token is used to validate sender signatures in your account, and the server token is used to send emails.

Once you’ve verified your sender signature and obtained your account and server token, you can configure the Postmark custom email provider in the WorkOS Dashboard:

Upon enabling the Postmark custom email provider, a WorkOS transactional message stream with the ID workos-transactional-s will be created for you. All WorkOS emails will be sent using this message stream.

Before configuring the Resend custom email provider in WorkOS, you’ll need to verify domains in your Resend account.

Once you’ve verified your domain, you’ll need to create an API key with the “Full access” permission on the Resend API Keys page.

“Full access” permission is required to fetch verified domains and send emails.

Once you’ve verified your domain and obtained an API key, you can configure the Resend custom email provider in the WorkOS Dashboard:

Before configuring the SendGrid custom email provider in WorkOS, you’ll need to verify your domain in the Sender Authentication settings in your SendGrid dashboard.

Once you’ve verified your domain, you’ll need to create an API key under Settings → API Keys in the SendGrid dashboard.

For API key permissions, select “Full Access” for Mail Send, and “Read Access” for Sender Authentication.

Once you’ve verified your domain and obtained an API key, you can configure the SendGrid custom email provider in the WorkOS Dashboard:

At any time when you are using a custom email provider, you can re-enable the WorkOS default provider by navigating to Emails → Providers and clicking Enable next to the WorkOS provider.

Alternatively, you can also remove your current custom email provider, which will automatically re-enable the WorkOS default provider.

If I am using a custom email provider, do I need to set up a custom email domain in WorkOS?

No. When using a custom email provider, you configure the sending domain in that provider, not in WorkOS. Any custom email domain set up in WorkOS will not be used.

What happens if emails fail to send via my custom email provider?

If emails fail to send via your custom email provider, you will be notified according to your notifications preferences via the WorkOS Dashboard, email, or Slack. You can also utilize the Emails → Events page in the WorkOS Dashboard to track email delivery failures.