Iterable keys 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 within 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 phoneNumber and want to send out SMS, but don't yet have their email address
Table of Contents
- Creating a placeholder email
- Updating the placeholder email to the user's actual email address
- Best practices when handling anonymous users
Placeholder email addresses in Iterable must end with ' @placeholder.email'. You can create placeholder emails by using the updateUser API endpoint.
For example, if adding users via our API:
Note: Our system prevents any emails following this pattern ('@placeholder.email') from receiving email messages.
Once you receive or have determined the user's actual email address, make a call to Iterable's updateEmail API endpoint. If you wanted to update firstname.lastname@example.org to email@example.com, the payload would look like this:
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.
IMPORTANT: You cannot use the updateEmail API endpoint if the newEmail already exists within Iterable. If the newEmail is an existing user profile, please see below ("Best Practices") for more information on how to handle this.
Note: Updating email addresses can only be done through the Iterable API. This cannot be updated by Segment.
When you receive or have determined the user's actual email address, use the updateEmail API endpoint
- As mentioned above, using the updateEmail API endpoint will result in the historical data and profile fields to be transferred from the placeholder email to the actual email address
- If you use the update API endpoint, that will create a completely separate user profile
- Once a completely separate user profile has been created for the user's actual email address, you will not be able to use the 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 contact properites:
- Use the getUser API endpoint to retrieve the placeholder email address's contact properties
- Make an update API call for the user's actual email address with the placeholder email addresses's contact properties that were retrieved from the previous getUser API call
- This will update the profile of the user's actual email address, so that it contains the contact properties of the placeholder email address
- IMPORTANT: This approach will overwrite the contact properties of the user's actual email address with the the contact properties of the placeholder email address
- For custom events:
- Use the getEvents 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, you will need to use the track API endpoint to create the custom events
- Make sure you edit the createdAt field in the API call to backfill the events
- Note: If the createdAt field is left blank, Iterable will automatically assign the current date and timestamp to that field
- IMPORTANT: Backfilling events will trigger any workflows that are triggered by those custom events
- We recommend adding filter nodes after the trigger node that will allow users with backfilled events to exit the workflow
- 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
You should make a disableDevice API call whenever the app is closed or when a user signs out, especially if you're using placeholder emails to track anonymous app behavior
- Call the registerDeviceToken when the app is opened again or when the user logs in again
- This is done to prevent duplicate sends to a device that may be shared amongst multiple people