SendGrid Setup

OneSignal's Email Messaging requires the use of a third-party email service provider to handle email delivery. All you have to do is set up the integration between the provider and OneSignal, and you'll be ready to send emails through OneSignal.

Step 1 Create SendGrid Account

If you do not already have a SendGrid account, create one now.

Note: SendGrid offers a free plan for low-volume delivery, which may be useful in testing.

Step 2 Configure your domain for email

Next, you can set up your domain so that it can send emails from SendGrid via your domain. We recommend this because setting up a domain will show your emails as coming from your domain rather than via sendgrid.net, and the links your users click as coming from your domain. For more information, follow the Domain Whitelabel Setup Guide.

To add your domain, go to Settings -> Sender Authentication -> Domain Authentication and add a whitelabel domain. We recommend mail.yourdomain.com but you can pick whatever you want.

Enabling Default Whitelabel will show your emails as coming from your domain.
Enabling Automated Security simplifies managing certain DNS records. Learn more

Next, click Save, and you will be brought to a page where you will get the information you need to update your domain settings.

If you selected Automated Security, you will be given three CNAME records you must change:

If you did not enable automated security, you will be given an MX and two TXT (SPF and DKIM) records you must change. You can also select the IP address you would like these to come from:

Next, you will need to update your DNS records for your domain host with the above information.

Once you have set up your DNS records, it make take up to 48 hours to work. You can check anytime by clicking the Validate Record button on the above SendGrid page.

How do I change my domain's email settings?

Step 3 Create API Key

In the SendGrid dashboard, go to Settings -> API Keys and click 'Create API Key'.

Next, name your API key something like OneSignal API Key and be sure to set permissions to Full Access. Click 'Create & View' when you are ready.

Next, click on the API key to copy it to your clipboard.

🚧
Your SendGrid API Key is like a password. Keep it safe and do not share it.

Step 4 Enable Email Messaging

Go to Settings > Platforms and scroll down until you see Email and click on it.

Next, you must configure your email settings. Select SendGrid as the provider, and paste in the API key you just copied in Step 2.

Delivery Defaults

Add the name and email address that you want your emails to come from (you may override these when sending a message from New Email)

Identity Verification

Recommended

By default, Identity Verification is disabled, however we recommend using it. You can enable Identity Verification here if you can support it.

👍
You're done! You can now start sending emails. Go to Sending Email Messages.

FAQ

How do I set up OneSignal if I already have an active Webhook in SendGrid?

To simplify setup and be able to access email delivery statistics, OneSignal will automatically configure Webhooks with SendGrid. Unfortunately, SendGrid only supports a single webhook for a given account. OneSignal requires webhooks to use Email Messaging, which may conflict with webhooks previously set up (e.g. for an analytics integration).

If you need the webhook you previously set up, you should contact us for possible workarounds.

If you do not need the webhook you previously set up, you must disable it. To do so, in SendGrid go to Settings -> Mail Settings and click 'Event Webhook':

Then set "Event Webhook Status to DISABLED and "Save".

What are the minimum restrictions I can allow?

The minimum access you need to allow is the Mail Send.

SendGrid Troubleshooting

Emails not sending

In your SendGrid Account under Activity, search the dates you sent the email.

Click the error email. If you see the issue with SendGrid, see the SendGrid Troubleshooting for details.

If you see the error with OneSignal, click the date to expand the error. In the section "Full response from the onesignal.com server:" this will hint at the area that is broken.

Error Unauthenticated email

In your SendGrid Account under Settings > Your Account > Personal Info, check that the email here matches the email in onesignal.com > Settings > From Email