SendGrid Setup
How to setup Sendgrid for use in OneSignal Email Messaging
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. Requirements
Don't have a Domain, DNS Provider or Email Service Provider?
No problem! Contact OneSignal's Sales Team and ask about Email Onboarding.
Step 2. 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: How to set up domain authentication.
SendGrid also provides Single Sender Verification if you do not have a domain.
Install DNS Records
If you selected Domain Authentication make sure your DNS Records are verified.
The SPF, DKIM and MX records should be configured automatically through SendGrid's setup wizard.
Step 3. Create API Key
In the SendGrid dashboard, go to Settings -> API Keys and click 'Create API Key'.
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.
What are the minimum API restrictions I can allow?
The minimum access you need to allow is as follows:
Keep your API key secret
Your SendGrid API Key is like a password. Keep it safe and do not share it.
Step 4. Enable Email Messaging
In OneSignal, navigate to Settings > Platforms and click Email to configure your email settings.
Select SendGrid as the provider.
Image selecting SendGrid from email settings
Paste your SendGrid API key into the provided field.
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.
Step 5. Add Subscribers
If you have a list of emails ready, select Upload CSV to Import Email Addresses. 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.
Step 6. Send Yourself a Test Email
In OneSignal > Messages > Email, select New Email.
Add a Subject and click Send Test Email. Input your email and press Send Test Message.
An email should arrive to your inbox shortly!
Troubleshooting
If running into issues, see our Email FAQ.
If stuck, contact support directly or email [email protected] for help.
For faster assistance, please provide:
- Your OneSignal App Id
- Details, logs, and/or screenshots of the issue.
- Steps to reproduce
Step 7. Set Custom User Properties
OneSignal creates channel-level device records under a unique Id called the player_id. A single user can have multiple player_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 setExternalUserId at any time to link all channels to a single user. For more details, see External User Ids.
All other event and user properties can be set using Data Tags. Setting this data is required for more complex segmentation and message personalization.
Step 8. Collect New Emails
Emails can be added into OneSignal using the following options outlined in our Import Email Addresses guide.
| Option | Description |
|---|---|
| Dashboard Upload | Upload a csv of emails and user data or manually add emails. |
| Server API | Programmatically add emails server side. |
SDK setEmail method | Add emails using our client side SDK. Recommended if using our SDKs for push or in-app messaging. |
| Email Web Prompt | A web prompt that allows user to include their own email address and phone number. |
Setup Complete!
Visit Email Tutorials for next steps.
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:
How do I whitelist OneSignal's IPs?
OneSignal uses GCP data centers located in Groningen, Netherlands. There are a wide range of IPs that can be used. You can copy-paste the following IP ranges to your whitelist (make sure to include your own IP Address if you have not!):
34.90.0.0/15,34.104.126.0/23,34.124.62.0/23,34.141.128.0/17,34.147.0.0/17,34.157.80.0/23,34.157.208.0/23,35.204.0.0/16,35.214.128.0/17,35.220.16.0/23,35.234.160.0/20,35.242.16.0/23,2600:1900:4060::/44
Updated 12 months ago