Handling Anonymous Users

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"
    }
}

# 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 docs@iterable.com, the payload would look like this:

{  
    "currentEmail": "example@placeholder.email",  
    "newEmail": "docs@iterable.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.

# Best practices for handling anonymous users

When you receive or have determined the user's actual email address, use the updateEmail API endpoint

• 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 contact properties:

  • Use the GET /api/users/{email} API endpoint to retrieve the placeholder email address's contact properties.

  • 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 contact properties of the user's actual email address with the the contact properties of 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 workflows that are triggered by those custom events.
  • Consider 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.

• Call POST /api/users/registerDeviceToken when a user signs in to the app and POST /api/users/disableDevice when they sign out. This prevents duplicate sends to a device shared amongst multiple people.