Handling Anonymous Users

There are many scenarios where you will have users that you need to track and connect with, but don't have their email address. This happens when you have mobile apps that don't require an email, SMS-first marketing, and more.

You might need to track anonymously 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

Iterable provides you with two different unique identifier fields, email and userId, and these can be applied to a project in three different ways:

• Hybrid project - uses both email and userId fields as unique identifiers.
• UserID-based project - uses just the userId field as a unique identifier.
• Email-based project - uses email as a unique identifier. (Limited availability: Only certain accounts have the option to create new email-based projects - learn more.)

To work with anonymous users in userID-based projects and hybrid projects, you will simply use the userId field instead of the email field to identify users.

If you are working in an email-based project, however, then all user profiles require a value for the email field. When you don't know the email address of a new user, but need to create a profile in Iterable, you will need to create a placeholder email address.

# In this article

# Manually 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": {
        "firstName": "Data",
        "catName": "Spot"
    }
}

# Automatically assigning a placeholder email

Instead of manually assigning placeholder email value, you can also ask Iterable to generate one for you when creating the user if you are working in an email-based project. Iterable doesn't create placeholder emails for userID-based and hybrid projects.

To do this, use the POST /api/users/update API endpoint to create a user. Provide a userId value and add the preferUserId parameter with a value of true.

An auto-generated placeholder email is made with a basic formula of: userId + + + Java hash + @placeholder.email.

When the userId value is longer than 52 characters, Iterable creates the placeholder email as: SHA1 hash + @placeholder.email.

For example, sending this request body to POST /api/users/update:

{
    "userId": "some-user-id",
    "preferUserId": true,
    "dataFields": {
        "firstName": "Mary",
        "lastName": "Lee"
    }
}

This creates a user with some-user-id+10593364321@placeholder.email as the assigned placeholder email:

{
    "user": {
        "email": "some-user-id+10593364321@placeholder.email",
        "userId": "some-user-id",
        "dataFields": {
          "firstName": "Mary",
          "lastName": "Lee",
            "email": "some-user-id+10593364321@placeholder.email",
            "signupDate": "2022-10-27 22:12:43 +00:00",
            "profileUpdatedAt": "2022-10-27 22:12:39 +00:00",
            "signupSource": "API",
            "userId": "some-user-id",
            "itblInternal": {
                "documentCreatedAt": "2022-10-27 22:12:43 +00:00",
                "emailDomain": "placeholder.email",
                "documentUpdatedAt": "2022-10-27 22:12:43 +00:00"
            }
        }
    }
}

When the userId is past 52 characters, Iterable assigns a placeholder email like this one: 4146832971d799352598ff1b5712c0b999f615d5@placeholder.email.

# Updating a placeholder email to the user's true email

When your user has converted from anonymous to known and they have provided their true 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.

# 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 can't 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 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 and POST /api/users/disableDevice when they sign out. This prevents duplicate sends to a device shared amongst multiple people.