Email Quickstart

This guide will walk you through all the steps to have full email integration with OneSignal.

Step 1 - Setup Email Service Provider Support

OneSignal Email Messaging requires an account with an eligible email service provider.

Email Providers
SendGrid Setup
Mailgun Setup
Mandrill Setup

Optional: Enable Identity Verification

We strongly recommend setting up Identity Verification on your server. When identity verification is enabled, OneSignal will look for an email authentication token from your server. This token is a SHA-256 hash of a user's email address, and ensures the user is who they say they are.

Step 2 - Add SDK Code

If you have not done so, we always recommend updating the OneSignal SDK to the latest version to get access to the latest features.

🚧
Email vs Push Records
Email and Push subscribers will have separate OneSignal Player IDs (user records). This is to manage the case where a user opts-out of one you can still send messages to the other. Email records cannot get push notifications and push records cannot get emails.

🚧
Note on Network Latency
If there are networking issues, functions may take 30+ seconds to return. In the code examples below we provide callbacks to track when these return.
Make sure to keep functions from blocking the user interface, otherwise your app may appear unresponsive to the user.

Setting the Users Email

The setEmail method allows you to set the user's email address with the OneSignal SDK. It is best to use this when the user provides their email. If setEmail called previously and the user changes their email, you need to call logoutEmail and then setEmail with new address to update it.

OneSignal.setEmail("[email protected]");

OneSignal.setEmail("[email protected]");

OneSignal.setEmail("[email protected]");

[OneSignal setEmail:@"[email protected]omain.com"];

OneSignal.setEmail("[email protected]");

OneSignal.setEmail("[email protected]");

OneSignal.SetEmail("[email protected]");

window.plugins.OneSignal.setEmail("[email protected]");

OneSignal.Current.SetEmail("[email protected]");

If you have a backend server, we strongly recommend using Identity Verification with your users. Your backend can generate an email authentication token and send it to your app or website. The following code also includes callbacks:

var email = "[email protected]";
var emailAuthHash = null; // Auth hash generated from your server

OneSignal.setEmail(email, emailAuthHash, function(emailPlayerId){
 console.log("Email Player Id: ", emailPlayerId)
});

String email = "[email protected]";
String emailAuthHash = null; // Auth hash generated from your server

OneSignal.setEmail(email, emailAuthHash, new OneSignal.EmailUpdateHandler() {
  @Override
  public void onSuccess() {
    // Email successfully synced with OneSignal
  }

  @Override
  public void onFailure(OneSignal.EmailUpdateError error) {
    // Error syncing email, check error.getType() and error.getMessage() for details
  }
});

let email = "[email protected]"
let emailAuthHash = null // Auth hash generated from your server

OneSignal.setEmail(email, withEmailAuthHashToken: emailAuthHash, withSuccess: {
    //The email has successfully been set.
}) { (error) in
    //Encountered an error while setting the email.
};

NSString *emailAddress = @"[email protected]";
NSString *emailAuthHash = null; // Auth hash generated from your server

[OneSignal setEmail:emailAddress withEmailAuthHashToken:emailAuthHash onSuccess: ^() {
    //The email has successfully been set.
} onFailure: ^(NSError *error) {
    //Encountered an error while setting the email.
}];

let email = "[email protected]";
let emailAuthHash = null; // Auth hash generated from your server

OneSignal.setEmail(email, emailAuthHash, (error) => {
    if (error) {
      console.log("Error Setting Email: ", error);

    } else {
      //successfully set email, call setExternalUserId to add your user id to the email record

    }
});

var email = "[email protected]";
var emailAuthHash = null; // Auth hash generated from your server

OneSignal.shared.setEmail(email: email, emailAuthHashToken: emailAuthHash).then((result) {
    //request succeeded
}).catchError((error) {
    //encountered an error
});

string email = "[email protected]";
string emailAuthHash = null; // Auth hash generated from your server

OneSignal.SetEmail(email, emailAuthHash, () => {
    //Successfully set email
}, (error) => {
    //Encountered error setting email
});

let email = "[email protected]";
let emailAuthHash = null; // Auth hash generated from your server

window.plugins.OneSignal.setEmail(email, emailAuthHash, function() {
    //Successfully set email

}, function(error) {
    //encountered an error setting email
    
});

string email = "[email protected]";
string emailAuthHash = null; // Auth hash generated from your server

OneSignal.Current.SetEmail(email, emailAuthHash, () => {
    //Successfully set email
}, (error) => {
    //Encountered error setting email
});

Recommendation: call setExternalUserId again after email address is provided to link the records together.

Logging Out

If your app or website implements logout functionality, you can call logoutEmail to dissociate the email from the device:

OneSignal.logoutEmail();

OneSignal.logoutEmail();

OneSignal.logoutEmail();

[OneSignal logoutEmail]

OneSignal.logoutEmail(function(successResponse) {
    //Successfully logged out of email
}, function(error) {
    //Failed to log out of email
});

await OneSignal.shared.logoutEmail();

OneSignal.LogoutEmail (() => {
    // Successfully logged out of email
}, (error) => {
    // Encountered error logging out of email
});

window.plugins.OneSignal.logoutEmail(function(successResponse) {
    //Successfully logged out of email
}, function(error) {
    //Failed to log out of email
});

OneSignal.Current.LogoutEmail();

// Optionally, you can also use callbacks
OneSignal.Current.LogoutEmail(() => {
  //handle success
}, (error) => {
  //handle failure
});

Email Subscription Observer

App only - Tracks changes to email subscriptions (for example, if the user sets their email, or logs out). In order to subscribe to email subscription changes, you can implement the following:

OneSignal.addEmailSubscriptionObserver(subscriptionObserver);

//Now, whenever the email subscription changes, this method will be called:

OSEmailSubscriptionObserver subscriptionObserver = new OSEmailSubscriptionObserver() {
   @Override
   public void onOSEmailSubscriptionChanged(OSEmailSubscriptionStateChanges stateChanges) {
   }
};

OneSignal.add(self as OSEmailSubscriptionObserver)

//Now, whenever the email subscription changes, this method will be called:

func onOSEmailSubscriptionChanged(_ stateChanges: OSEmailSubscriptionStateChanges!) { 
    
}

[OneSignal addEmailSubscriptionObserver:self];

//Now, whenever the email subscription changes, this method will be called:

-(void)onOSEmailSubscriptionChanged:(OSEmailSubscriptionStateChanges *)stateChanges {
    
}

// Requires React Native SDK 4.x
OneSignal.addEmailSubscriptionObserver((event) => {
    console.log("OneSignal: email subscription changed: ", event);
});

//Requires Flutter SDK 3.x
OneSignal.shared.setEmailSubscriptionObserver(
        (OSEmailSubscriptionStateChanges changes) {
      print("OneSignal: email subscription changed: ${changes.jsonRepresentation()}");
});

void Start() {
    OneSignal.emailSubscriptionObserver += OneSignal_emailSubscriptionObserver;
}

//Now, whenever the email subscription changes, this method will be called:

private void OneSignal_emailSubscriptionObserver(OSEmailSubscriptionStateChanges stateChanges) {
    string newEmailAddress = stateChanges.to.emailAddress;
}

window.plugins.OneSignal.addEmailSubscriptionObserver(function(stateChanges) {
    //Email subscription state changed
    let newEmailAddress = stateChanges.to.emailAddress;
    let newUserId = stateChanges.to.emailUserId;
});

//Currently not available

Step 3 - Import Emails

If you already have a list of email addresses and wish to immediately start sending emails, you can import them into OneSignal.

You can import emails through our Dashboard or API. Details and code examples are available in Import Email Addresses guide.

Step 4 - External User Ids

Each Email record in OneSignal gets a unique Player Id (OneSignal's Device Id). The Email Player Id will be different from the Push record Player Id.

In order to tie the Email and Push Player Id together under a single User Id, leverage the OneSignal setExternalUserId SDK method. It is recommended to call this method after the email is set.

Step 5 - Send Tags

To personalize your messages, we recommend adding the following tags to users if you have access to this user information. These tag key names are special and only these names will work with Merge Tags in email.

Tag Key	Tag Value
`real_name`	user’s full real name
`first_name`	user’s first name
`last_name`	user’s last name
`user_name`	name that users give themselves; often not a real name (e.g. PokeCatcher22)
`salutation`	if you wish to refer to users by a salutation (Ms, Dr, Hon, etc)

Please refer to the sendTag and sendTags methods in Data Tag Implementation to learn how to send them.

Step 6 - Send Emails

Send emails using OneSignal's:

👍
Done!
You are a OneSignal Email Pro!

Email Quickstart

Step 1 - Setup Email Service Provider Support

Optional: Enable Identity Verification

Step 2 - Add SDK Code

🚧
Email vs Push Records

🚧
Note on Network Latency

Setting the Users Email

Logging Out

Email Subscription Observer

Step 3 - Import Emails

Step 4 - External User Ids

Step 5 - Send Tags

Step 6 - Send Emails

👍
Done!

Step 1 - Setup Email Service Provider Support

Optional: Enable Identity Verification

Step 2 - Add SDK Code

🚧Email vs Push Records

🚧Note on Network Latency

Setting the Users Email

Logging Out

Email Subscription Observer

Step 3 - Import Emails

Step 4 - External User Ids

Step 5 - Send Tags

Step 6 - Send Emails

👍Done!

🚧
Email vs Push Records

🚧
Note on Network Latency

👍
Done!