OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Email Quickstart

How to set up email messaging on your app or website

Beta Feature

OneSignal has recently added support for email as a messaging channel. To learn more, please see our Email Overview.

About the Beta

To send emails through OneSignal, you'll need the following:

  1. You use the OneSignal SDK in your mobile app or website (note: Wordpress is not yet supported, and email is not a standalone feature)

  2. You already collect, or plan to collect, email addresses of your users for transactional and marketing use, and have added the appropriate code to send those to OneSignal.

  3. You have an account with a supported email service provider.

Being in the beta is an opportunity for you to help shape the product through feedback to the OneSignal team. You will receive updates on issues, new features, and changes as the service matures and are encouraged to provide feedback.

Beta Limitations

Feature
Limitation

Delivery Statistics

Limited

Resolved: April

Delivery Scheduling

Per-user scheduling disabled

Automated Messages

Not yet supported

A/B Testing

Not yet supported

Standalone email support

Not yet supported (learn more)


Email Service Provider Support

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

Sendgrid

Supported

Mailgun

Supported

Mandrill

Supported

Amazon SES

Coming soon

Other

Does this mean I still have to pay another provider for email?
What should I do if I don't have an email provider?
What are the differences between email service providers?


New Concepts in Email Messaging

Email introduces a few new concepts to OneSignal that are worth reviewing.

Identity Verification

See Identity Verification

Merge Tags

Emails support the same Message Personalization capabilities supported in push notifications, meaning you can personalize your emails, e.g.:

Hi {{first_name | default: there }}, you're invited to an exclusive group!

Subscriptions

Email handles subscriptions a bit differently than push notifications. Users may unsubscribe themselves from emails, as well as mark emails as spam. These may show up in Delivery. You may also unsubscribe users manually from All Users.


Setup Email

To set up email, you'll need to add code to your app or website and then set up your email service provider.

Step 1. Enable Identity Verification

Recommended

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

You will need to update your app / website's OneSignal SDK to the latest version in order to use the new email methods. Next, you will need to add the appropriate code to begin sending and handling email.

Note as with all OneSignal code, 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. Meanwhile be sure to keep functions from blocking the user interface, otherwise your app may appear unresponsive to the user.

Setting the User's Email

setEmail allows you to set the user's email address with the OneSignal SDK. We offer several overloaded versions of this method.

OneSignal.setEmail("example@domain.com");
[OneSignal setEmail:@"example@domain.com"];
OneSignal.setEmail("example@domain.com");
OneSignal.setEmail("example@domain.com");
window.plugins.OneSignal.setEmail("example@domain.com");
OneSignal.setEmail("example@domain.com");
OneSignal.SetEmail("example@domain.com");

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:

String email = "example@domain.com";
String emailAuthHash = "..."; // Email 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
  }
});
NSString *hashToken = //hash token from your server
NSString *emailAddress = @"example@domain.com";
[OneSignal setEmail:emailAddress withEmailAuthHashToken:hashToken onSuccess: ^() {
    //The email has successfully been set.
} onFailure: ^(NSError *error) {
    //Encountered an error while setting the email.
}];
let emailAuthHash = //generated on your backend server
let email = "example@domain.com";
OneSignal.setEmail(email, withEmailAuthHashToken: emailAuthHash, withSuccess: {
    //The email has successfully been set.
}) { (error) in
    //Encountered an error while setting the email.
};
var emailAuthHash = "..."; // Email auth hash generated from your server
OneSignal.setEmail("example@domain.com, {
 emailAuthHash: emailAuthHash
});
let emailAuthToken = ""; //from your backend server

window.plugins.OneSignal.setEmail("example@domain.com", emailAuthToken, function() {
    //Successfully set email

}, function(error) {
    //encountered an error setting email
    
});
let emailAuthToken = ""; //from your backend server

OneSignal.setEmail("example@domain.com", emailAuthToken, (error) => {
    if (error == undefined) {
        //successfully set email

    } else {
        //encountered an error

    }
});
string emailAuthToken = ""; //from your backend server

OneSignal.SetEmail("example@domain.com", emailAuthToken, () => {
    //Successfully set email
}, (error) => {
    //Encountered error setting email
});

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();
window.plugins.OneSignal.logoutEmail(function(successResponse) {
    //Successfully logged out of email
}, function(error) {
    //Failed to log out of email
});
OneSignal.logoutEmail(function(successResponse) {
    //Successfully logged out of email
}, function(error) {
    //Failed to log out of email
});
OneSignal.LogoutEmail (() => {
    // Successfully logged out of email
}, (error) => {
    // Encountered error logging out of email
});

Email Subscription Observer

App only - We have also added a new email subscription observer to track changes to email subscriptions (ie. the user sets their email or logs out). In order to subscribe to email subscription changes you can implement the following:

OneSignal.addEmailSubscriptionObserver(subscriptionObserver);
[OneSignal addEmailSubscriptionObserver:self];
OneSignal.add(self as OSEmailSubscriptionObserver)
window.plugins.OneSignal.addEmailSubscriptionObserver(function(stateChanges) {
    //Email subscription state changed
    let newEmailAddress = stateChanges.to.emailAddress;
    let newUserId = stateChanges.to.emailUserId;
});
componentDidMount() {
    this.onEmailSubscriptionChange = this.onEmailSubscriptionChange.bind(this);

    OneSignal.addEventListener('emailSubscription', this.onEmailSubscriptionChange);
}
void Start() {
    OneSignal.emailSubscriptionObserver += OneSignal_emailSubscriptionObserver;
}

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

OSEmailSubscriptionObserver subscriptionObserver = new OSEmailSubscriptionObserver() {
   @Override
   public void onOSEmailSubscriptionChanged(OSEmailSubscriptionStateChanges stateChanges) {
   }
};
-(void)onOSEmailSubscriptionChanged:(OSEmailSubscriptionStateChanges *)stateChanges {
    
}
func onOSEmailSubscriptionChanged(_ stateChanges: OSEmailSubscriptionStateChanges!) { 
    
}
// See above
onEmailSubscriptionChange(registration) {
    let emailAddress = registration.emailAddress;
    let emailUserId = registration.emailUserId;
}
private void OneSignal_emailSubscriptionObserver(OSEmailSubscriptionStateChanges stateChanges) {
    string newEmailAddress = stateChanges.to.emailAddress;
}

Step 3. Import Emails

Recommended

If your app or website collects email addresses, we recommend importing them in a one-time step so that you can immediately message your entire userbase. Code examples are available in Import Email Addresses to help you do this.

Step 4. Send Tags

Recommended

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.

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)

If you have other tags in mind for use in email, please contact us to give us feedback on what other tags you'd like to have integrated.

Please refer to the sendTag and sendTags methods for iOS, Android, or Web to learn how to send them.


Done! Now set up your email service provider.