Mailchimp Setup

How to setup Mailchimp 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.


Mailchimp Testing

When testing Mailchimp without one of their paid plans, you can only send to email addresses that are from the verified domain.

Step 2. Configure your domain for email

Navigate to the Mailchimp Transactional Email tool (formerly Mandrill) Settings > Domains > Sending Domains and add your domain if you have not done so already.

When your domain is added, click View DKIM/SPF Setup Instructions, which provides the appropriate DNS settings you will need to update your domain. You can also verify your domain by clicking View details and receiving an email to your domain.

Next, you will need to update your DNS records for your domain host. Follow Mailchimp's instructions to learn more.

Once you have set up your DNS records, it make take up to 48 hours to work. Mailchimp will email you when your domain is verified.

Step 3. Create API Key

In Mailchimp's Transactional Email Tool (formerly Mandrill), click Settings and + New API Key.

Optional: Name your API key something like OneSignal API Key.

You will see your key was created successfully. Next, highlight the API key and copy it to your clipboard. Also note your SMTP Username here.


CAUTION! API Keys need to be secret

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

Which API Key Permissions do I need to enable?

Since our API does a lot of communication between both platforms, you will likely need these permissions at the least:

Step 4. Enable Email Messaging

In OneSignal, go to Settings > Platforms > Email

Select Mailchimp as the provider, and paste in the API key and SMTP Username.

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.



You can now start sending emails. Go to Sending Email Messages.

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!



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 subscription_id. The subscription records are tied to a unique onesignal_id or OneSignal's internal User 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 OneSignal.login() at any time to link all channels to a single user. For more details, see Aliases & External 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.

Dashboard UploadUpload a csv of emails and user data or manually add emails.
Server APIProgrammatically add emails server side.
SDK setEmail methodAdd emails using our client side SDK. Recommended if using our SDKs for push or in-app messaging.
Email Web PromptA web prompt that allows user to include their own email address and phone number.


Setup Complete!

Visit Email Tutorials for next steps.

Exporting Emails

  1. Audience Page Access: Go to Audience > Segments.
Navigating to Segments

Navigating to Segments

  1. Segment Selection: Find the Segment you wish to export.
  2. Export Option: Click the context menu next to the Edit button.
Selecting audience to export

Selecting audience to export

  1. Initiate Export: Select Export as CSV. This redirects you to the Audience Export Page.
Creating an export

Creating an export

  1. Download File: Click Export As CSV to receive a Zip archive.
Download exported CSV

Download exported CSV

  1. Extract Data: Unzip the archive to access the CSV files.

Obtaining API Key

  1. Navigate to your MailChimp dashboard and click your avatar in the top-right corner to reveal the popup menu.
Opening Drop-down Menu

Clicking the user avatar

  1. Choose Account & Billing.
Selecting Account & Billing

Selecting the Account & Billing link

  1. Click on Extras, then select API Keys.
Selecting Extras > API keys

Selecting Extras > API keys

  1. Click the Create A Key button located beneath your existing API keys.
Clicking Creating A Key

Clicking the Creating A Key button

  1. Provide a name for the key and click Generate Key.
Naming and generating key

Naming the key and clicking the Generate Key button

  1. Copy your API key.
Copying key to clipboard

Copying key to clipboard


How do I allowlist OneSignal's IPs?

See the requirements in our REST API Overview for details.