SendGrid Setup
This guide explains how to integrate your SendGrid emails into OneSignal.
Requirements
Setup
1. SendGrid Sender Authentication
It is recommended to use SendGrid's "Domain Authentication" so that SendGrid sends emails via your domain rather than via sendgrid.net
, and the links your users click as coming from your domain.
Recommended: Follow SendGrid's guide on How to set up domain authentication.
SendGrid also provides Single Sender Verification if you do not have a domain.
2. Install DNS Records
If you selected Domain Authentication make sure your DNS Records are verified.
![Screen Shot 2021-10-20 at 1.18.12 PM.png](https://files.readme.io/3ceb5db-Screen_Shot_2021-10-20_at_1.18.12_PM.png)
The SPF, DKIM and MX records should be configured automatically through SendGrid's setup wizard.
![esp-sendgrid-domain-3.jpg](https://files.readme.io/41879e3-esp-sendgrid-domain-3.jpg)
3. Create API Key
In the SendGrid dashboard, go to Settings -> API Keys and click 'Create API Key'.
![esp-sendgrid-apikey.jpg](https://files.readme.io/f794466-esp-sendgrid-apikey.jpg)
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.
![esp-sendgrid-apikey-2.jpg](https://files.readme.io/afe1836-esp-sendgrid-apikey-2.jpg)
Next, click on the API key to copy it to your clipboard.
![esp-sendgrid-apikey-3.jpg](https://files.readme.io/b8a9822-esp-sendgrid-apikey-3.jpg)
What are the minimum API restrictions I can allow?
The minimum access you need to allow is as follows:
![Screen Shot 2021-12-09 at 1.25.57 PM.png](https://files.readme.io/2d82f50-Screen_Shot_2021-12-09_at_1.25.57_PM.png)
Don't block OneSignal from accessing SendGrid!
If you are using SendGrid's allowlisting functionality, make sure to add OneSignal to this list.
See below FAQ How do I allowlist OneSignal's IPs?
4. Disable Sendgrid Subscription Tracking
OneSignal automatically adds its own default unsubscribe links for every email sent.
Disable Subscription Tracking in sendgrid to prevent Sendgrid from automatically adding its own unsubscribe link to the bottom of text and HTML emails.
![](https://files.readme.io/1b863e8-Sendgrid_Tracking_Settings.png)
5. Enable Email Messaging
In OneSignal, navigate to Settings > Platforms > Email and Activate Email to configure your email settings.
Select SendGrid as the provider.
![sendgrid.png 1549](https://files.readme.io/a42b5c0-Screenshot_2023-09-27_at_4.38.36_PM.png)
Image selecting SendGrid from email settings
Paste your SendGrid API key into the provided field.
![sendgrid-1.png 1549](https://files.readme.io/0431d6a-Screenshot_2023-09-27_at_4.39.12_PM.png)
Image showing where to enter your API Key
Delivery Defaults
Add the default name and email address you want your emails to come from (these can be changed later).
Press Done when finished.
![Email Configuration Success Banner.png](https://files.readme.io/4b63e41-Screenshot_2023-09-27_at_4.41.02_PM.png)
6. Add Subscribers
If you have a list of emails ready, select Upload CSV or you can always do this again later.
If you have a website and want to prompt users to provide their email. Select Add Web Prompt to use OneSignal's Email Web Prompt.
![Screen Shot 2021-10-20 at 3.33.45 PM.png](https://files.readme.io/6ba703e-Screenshot_2023-09-27_at_4.39.54_PM.png)
7. Testing
Navigate to Messages > Email, select New Email.
Add a Subject
, select an Editing experience (Drag & Drop Editor is a good start) and click Send Test Email.
![Screen Shot 2021-11-18 at 6.00.46 PM.png](https://files.readme.io/10d1976-Screenshot_2023-09-27_at_4.49.08_PM.png)
Input your email and press Send Test Email. An email should arrive to your inbox shortly!
Troubleshooting
If running into issues, see our Email FAQ.
If stuck, contact support directly or email support@onesignal.com for help.
For faster assistance, please provide:
- Your OneSignal App Id
- Details, logs, and/or screenshots of the issue.
- Steps to reproduce
Recommended
Identify Users
Required if using integrations.
Recommended for messaging across multiple channels (push, email, sms).
OneSignal creates subscription-level records under a unique ID called the subscription_id. A single user can have multiple subscription_id records based on how many devices, email addresses, and phone numbers they use to interact with your app.
If your app has its own login system to track users, call login
at any time to link all channels to a single user. For more details, see Aliases & External ID.
Collect New Emails
Recommended if using Email and SMS messaging.
There are several ways to pass new email addresses into OneSignal:
- Use OneSignal's Frontend SDK to capture new emails. See Email SDK Methods.
- Use the Create user or Create subscription APIs to add emails from your server.
- If you want to import emails via CSV, see Import Email Addresses.
Add Data Tags
Optional
Tags are custom key : value
pairs of String data used for tracking user events and properties. Setting tags is required for more complex segmentation and message personalization.
See Data Tags for more details.
Setup Complete!
Visit Email Tutorials for next steps.
Exporting Emails
- Contact Lists Navigation: Go to
Marketing > Contacts
.
-
Navigating to Contacts page
- List Identification: Locate the list you want to export.
- Export Selection: Open the context menu under the Action list header.
![Selecting Contact List to export](https://files.readme.io/d900c5a-step-3-50.png)
Selecting Contact List to export
- Begin Export: Click Export. This takes you to
Contact > Active Exports
. - Download File: Wait until the Status shows 'Ready for Download', then click Download CSV.
![Downloading the exported CSV](https://files.readme.io/2d1c12f-step-5-50.png)
Downloading the exported CSV
- File Retrieval: The file will be saved in your downloads directory.
Obtaining API Key
- Navigate to your Sendgrid dashboard and open Settings from the left sidebar.
![Navigating to Settings > API Keys](https://files.readme.io/cf3fe33-step-1-50.png)
Navigating to Settings > API Keys
- Select API Keys.
![Clicking the Create API Key button](https://files.readme.io/c3045de-step-2-50.png)
Clicking the Create API Key button
- Name your key. Optionally, opt for Restricted Access for specific permissions.
![Naming the key and setting permissions](https://files.readme.io/8770efc-step-3-50.png)
Naming the key and setting permissions
If using Restricted Access, ensure that you grant Full Access privileges for Marketing.
![Granting Full Access to Marketing](https://files.readme.io/83d80f8-step-4-50.png)
Granting Full Access to Marketing
- Click Create & View.
![Clicking the Create & View button](https://files.readme.io/f92f0c4-step-5-50.png)
Clicking the Create & View button
- Copy your API key.
![Copying the key](https://files.readme.io/64034da-step-6-50.png)
Copying the key
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 for email analytics, which may conflict with webhooks previously set up (e.g. for an analytics integration).
If you need the webhook you have currently set up, you can forward the request to https://onesignal.com/email/hooks/sendgrid
. Setup a timeout of 30 seconds for best results.
If you do not need the webhook you previously set up, you must change it. In SendGrid, go to Settings > Mail Settings and click 'Event Webhook'. The HTTP Post URL should be https://onesignal.com/email/hooks/sendgrid
and have the minimum settings shown:
![Screen Shot 2021-10-20 at 2.05.47 PM.png](https://files.readme.io/989f714-Screen_Shot_2021-10-20_at_2.05.47_PM.png)
How do I allowlist OneSignal's IPs?
See the requirements in our REST API Overview for details.
![Screen Shot 2022-05-27 at 5.32.06 PM.png](https://files.readme.io/b7550d9-Screen_Shot_2022-05-27_at_5.32.06_PM.png)
Updated 9 months ago