Iterable identifies users by email address. As a result, user profiles created
via API, Segment or another method require an
email
field.
If you don't know the email address of a user, but would like to create a profile in Iterable, you will need to create a placeholder email address.
Placeholder email addresses are useful in the following scenarios:
- You do not have a user's email address but want to track and save their event history
- You have the user's device token but not their email address and want to send them a push notification
- You have the user's phone number and want to send out SMS, but don't yet have their email address
Table of contents
Creating a placeholder email
Placeholder email addresses in Iterable must end with @placeholder.email
.
You can create placeholder emails by using the POST /api/users/update
API endpoint.
For example, if adding users via through the API:
{ "email": "example@placeholder.email", "dataFields": { "catName": "Lucifer" } }
NOTE
Iterable does not send emails to @placeholder.email
addresses.
Updating the placeholder email to the user's actual email address
Once you receive or have determined the user's actual email address, make a call
to Iterable's POST /api/users/updateEmail
.
endpoint.
For example, to update an example@placeholder.email
email to user@example.com
,
the payload would look like this:
{ "currentEmail": "example@placeholder.email", "newEmail": "user@example.com" }
This call must be made in order for the historical data and profile fields to be transferred to the new email address for the user in Iterable.
NOTES
- You cannot use the
POST /api/users/updateEmail
endpoint if thenewEmail
value already exists in Iterable. IfnewEmail
is an existing user profile, see below for information about how to handle this. - Updating email addresses can only be done through Iterable's API. It cannot be done through Segment.
Best practices for handling anonymous users
When you receive or have determined the user's actual email address, use the
POST /api/users/updateEmail
API endpoint to update the existing user's email address.
The
POST /api/users/updateEmail
API endpoint transfers historical data and profile fields from the placeholder email to the new email address.-
The
POST /api/users/update
API endpoint creates a completely separate user profile.Once a completely separate user profile has been created for the user's actual email address, you cannot use the
POST /api/users/updateEmail
API endpoint to update the placeholder email address to the user's actual email address.
If a completely separate user profile has been created and you wish to merge the historical data and profile fields from a placeholder email address to the user's actual email address, you will need to complete the following:
-
For user profile fields:
Use the
GET /api/users/{email}
API endpoint to retrieve the user profile fields associate with the placeholder email address.-
Use the
POST /api/users/update
API endpoint to set the placeholder email address's properties (fetched above) on the actual email address's profile.WARNING
This approach will overwrite the user profile fields for the user's actual email address with the the user profile fields from the placeholder email address.
-
For custom events:
Use the
GET /api/events/{email}
API endpoint to retrieve the placeholder email address's custom events.To record the events of the placeholder email address onto the user's actual address profile, use the
POST /api/events/trackBulk
to create the custom events.Make sure you edit the
createdAt
field in the API call to backfill the events.
NOTES
- If the
createdAt
field is left blank, Iterable will automatically assign the current date and timestamp to that field . - Backfilling events will trigger any journeys that are triggered by those custom events.
- Consider adding a filter tile after the Start tile that will allow users with backfilled events to exit the journey. This can be done through the creation date of the custom event or by including a data field in the event itself that notes that it is a backfilled event.
Call
POST /api/users/registerDeviceToken
when a user signs in to the app andPOST /api/users/disableDevice
when they sign out. This prevents duplicate sends to a device shared amongst multiple people.
Comments
0 comments
Please sign in to leave a comment.