How to set up email messaging on your app or website
The methods below require the OneSignal SDK versions 3 & 4.
It is recommended to upgrade to our latest version 5 SDKs for User Model APIs.
See Update to User Model for migration steps.
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 and Push subscribers will have separate OneSignal Subscription 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.
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.
setEmail
MethodAllows 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, callingsetEmail
again will update that record with the new email address.
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.
Recommendation: call setExternalUserId
again within the setEmail
callback to link the records together.
logoutEmail
MethodIf your app or website implements logout functionality, you can call logoutEmail
to dissociate the email from the device:
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:
Event Object Property | Type |
---|---|
email | string |
getEmailId
MethodWeb only - Returns a Promise
that resolves to the stored OneSignal Subscription 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 Subscription 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 Subscription ID and tie it to the new Push Subscription ID.
Callback function sets the first parameter to the stored Email Record’s OneSignal Subscription ID if one is set, otherwise the first parameter is set to null.
How to set up email messaging on your app or website
The methods below require the OneSignal SDK versions 3 & 4.
It is recommended to upgrade to our latest version 5 SDKs for User Model APIs.
See Update to User Model for migration steps.
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 and Push subscribers will have separate OneSignal Subscription 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.
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.
setEmail
MethodAllows 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, callingsetEmail
again will update that record with the new email address.
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.
Recommendation: call setExternalUserId
again within the setEmail
callback to link the records together.
logoutEmail
MethodIf your app or website implements logout functionality, you can call logoutEmail
to dissociate the email from the device:
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:
Event Object Property | Type |
---|---|
email | string |
getEmailId
MethodWeb only - Returns a Promise
that resolves to the stored OneSignal Subscription 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 Subscription 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 Subscription ID and tie it to the new Push Subscription ID.
Callback function sets the first parameter to the stored Email Record’s OneSignal Subscription ID if one is set, otherwise the first parameter is set to null.