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 SDK Methods

How to set up email messaging on your app or website

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

setEmail Method

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

It is best to call 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.push(function() {
  OneSignal.setEmail("[email protected]")          
    .then(function(emailId) {
      // Callback called when email have finished sending
      console.log("emailId: ", emailId);  
    }); 
});
OneSignal.setEmail("[email protected]");
OneSignal.setEmail("[email protected]");
[OneSignal setEmail:@"[email protected]"];
OneSignal.SetEmail("[email protected]");
OneSignal.setEmail("[email protected]");
OneSignal.setEmail("[email protected]");
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
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.

🚧

External User Id Setup

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

Logout Email

logoutEmail Method

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

OneSignal.push(function() {
  OneSignal.logoutEmail();
});
OneSignal.logoutEmail();
OneSignal.logoutEmail();
[OneSignal logoutEmail]
OneSignal.LogoutEmail (() => {
    // Successfully logged out of email
}, (error) => {
    // Encountered error logging out of email
});
OneSignal.logoutEmail(function(successResponse) {
    //Successfully logged out of email
}, function(error) {
    //Failed to log out of email
});
await OneSignal.shared.logoutEmail();
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
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

addEmailSubscriptionObserver Method

Mobile 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 {
    
}
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;
}
// 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()}");
});
// Ionic 5 Capacitor may need to use (window as any).plugins.OneSignal
window.plugins.OneSignal.addEmailSubscriptionObserver(function(stateChanges) {
    //Email subscription state changed
    let newEmailAddress = stateChanges.to.emailAddress;
    let newUserId = stateChanges.to.emailUserId;
});
//Currently not available

getEmailId Method

Web only - Returns a Promise that resolves to the stored OneSignal Player ID of the Email Record if one is set using the setEmail method. Otherwise the Promise resolves to null. If the user isn't already subscribed, this function will resolve to null immediately.

Once created, the Email Record Player ID will not change. If the user unsubscribes from web push, for example by clearing their browser data, you should call setEmail with the same email as before to maintain the same Email Record Player ID and tie it to the new Push Player ID.

Callback function sets the first parameter to the stored Email Record's OneSignal Player ID if one is set, otherwise the first parameter is set to null.

OneSignal.push(function() {
  OneSignal.getEmailId(function(emailId) {
    console.log("OneSignal Email ID:", emailId);
    // (Output) OneSignal Email ID: 270a35cd-4dda-4b3f-b04e-41d7463a2316    
  });
});
// Both examples are valid
OneSignal.push(function() {
  OneSignal.getEmailId().then(function(emailId) {
    console.log("OneSignal Email ID:", emailId);
    // (Output) OneSignal Email ID: 270a35cd-4dda-4b3f-b04e-41d7463a2316    
  });
});

Updated about a month ago



Email SDK Methods


How to set up email messaging on your app or website

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.