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 |
|---|
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 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
The setEmail method allows you to set the user's email address with the OneSignal SDK. We offer several overloaded versions of this method.
OneSignal.setEmail("[email protected]");
[OneSignal setEmail:@"[email protected]"];
OneSignal.setEmail("[email protected]");
OneSignal.setEmail("[email protected]");
window.plugins.OneSignal.setEmail("[email protected]");
OneSignal.setEmail("[email protected]");
OneSignal.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:
String email = "[email protected]";
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 = @"[email protected]";
[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 = "[email protected]";
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("[email protected], {
emailAuthHash: emailAuthHash
});
let emailAuthToken = ""; //from your backend server
window.plugins.OneSignal.setEmail("[email protected]", emailAuthToken, function() {
//Successfully set email
}, function(error) {
//encountered an error setting email
});
let emailAuthToken = ""; //from your backend server
OneSignal.setEmail("[email protected]", emailAuthToken, (error) => {
if (error == undefined) {
//successfully set email
} else {
//encountered an error
}
});
string emailAuthToken = ""; //from your backend server
OneSignal.SetEmail("[email protected]", 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 an 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
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 - 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 |
|---|---|
| user’s full real name |
| user’s first name |
| user’s last name |
| name that users give themselves; often not a real name (e.g. PokeCatcher22) |
| if you wish to refer to users by a salutation (Ms, Dr, Hon, etc) |
Please refer to the sendTag and sendTags methodsto learn how to send them.
Step 5 - Send Emails
Send emails using OneSignal's:
Done!
You are a OneSignal Email Pro!
Updated about a month ago