Outbound needs to know certain information about your users to send messages to them effectively. You can send this user data to Outbound using any of the following methods:

  • Use the Identify User endpoint in the Outbound REST API
  • Use the identify() method in any of the Outbound integration options
  • Go to the Users page in your Outbound account and upload a CSV file

After the initial sync, you should try to keep your Outbound user database in sync with the user database in your system. A best practice is to identify users with Outbound whenever one of the following events occurs:

  • A user is added to your database
  • A user's information is updated in your database

Topics covered in this document:

User properties

Users are represented by the following properties. Some Outbound libraries may not implement all the properties or use slightly different names. For implementation details, see the docs for your library.

Name Type Mandatory Description
user_id string yes Unique user ID. See User id
first_name string no User's first name. Used in messages
last_name string no User's last name. Used in messages
email string no User's email. See Email address
apns array of strings no Apple Push Notification service (APNs) device tokens. See Device tokens
gcm array of strings no Google Cloud Messaging (GCM) device tokens. Also accepts Firebase Cloud Messaging (FCM) tokens. See Device tokens
phone_number string no User's phone number with country code. Example: '+1 555-123-4567'. See Phone number
timezone string no A valid tz database name. Example: 'Europe/Berlin'
attributes object no Custom user attributes, such as 'username', 'date of birth', or 'address'. See Attributes
previous_id string no A previously assigned id. See Aliasing users
group_id string no A custom name for a group of users. See Group id and attributes
group_attributes object no Custom attributes shared by all members of the named group. See Group id and attributes
User id

A user ID is the unique identifier for a user. The value can be a string or number. Outbound always treats it as a string and converts any number value to a string.

A user ID should be static. If possible, it should be the same value you use to identify the user in your own system.

Sometimes you don't have an id for a user yet but you still want to send messages to the user with Outbound. One solution is to generate an anonymous id and use it as the value of the user_id property. Once the user is identified, you can alias the known user to the anonymous user by specifying the anonymous user ID as the known user's previous_id. See Aliasing users.

Email address

Email addresses are required for Outbound campaigns that send email messages. All email addresses are validated using Mailgun's email validation API. Outbound won't save an address unless it's valid.

Phone number

Phone numbers are required for Outbound campaigns that send SMS messages or make voice calls. Phone numbers are validated using a validation library by Google. Outbound won't save a number unless it's valid.

A common issue with phone validation is country codes. Example: '+1 555-123-4567'. If the phone number doesn't have a country code, Outbound assumes it's a U.S. phone number.

Device tokens

If you have an iOS or Android mobile app and want to use push notifications in your Outbound campaigns, include the user's Apple Push Notification service (APNs) token, Google Cloud Messaging (GCM) token, or Firebase Cloud Messaging (FCM) token. Use the gcm property to specify the GCM or FCM token.


The attributes property takes an object specifying one or more custom attributes for a user. Example:

"attributes": {
  "address": {
    "street": "395 Collins St",
    "city": "Melbourne"

The team responsible for creating campaigns in Outbound could then select the address.street or attribute in the example to define a filter. They could also insert the values in a message by selecting the attributes from the "@" variable list when composing the campaign message.

To view the user attributes already sent to or tracked in Outbound, go to the Users page (Settings > Users) in Outbound.


Group id and attributes

A group id is a custom name for users in Outbound who share one or more attributes defined in the group_attributes object.

For example, suppose you want an Outbound campaign to only send messages to your customers in Australia. You might assign a group id of "au" to each of your Australian users in Outbound, then specify a group attribute named location with a value of "Australia". Example:

"user_id": "",
"group_id": "au",
"group_attributes": {"location": "Australia"}

Your organization can then create Outbound campaigns that send messages only to users who have a location attribute equal to "Australia".

A user can only belong to one group at a time.

You can create a group by simply specifying an custom group id, such as "au", when sending data about a user to Outbound.

You only need to specify the group_attributes values in the first request. You can update the attributes in another request. However, you must set a group_id for each user you want to include in the group.

JSON example
  "user_id": "",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "",
  "phone_number": "+61 3 9003 6275",
  "timezone": "Australia/Melbourne",
  "attributes": {
    "address": {
      "street": "395 Collins St",
      "city": "Melbourne"
  "previous_id": "anonymous_user_123",
  "group_id": "au",
  "group_attributes": {"location": "Australia"}

For other data formats, see the docs for your integration option.

Aliasing users

Outbound lets you alias users -- that is, associate one user id to another user id. This ability is useful to prevent multiple records for the same user in Outbound.

For example, Outbound's JavaScript library and some third-party libraries assign a user id to any anonymous user who visits the application. If the anonymous user then signs in, you can alias the anonymous user's id with the known user's id in Outbound. Example:


  "user_id": "",
  "previous_id": "anonymous_user_123"

For implementation details, see the docs for your integration option.

The attributes of both records are combined. If they share a common attribute, the value of the most recent identify request is used. Example:

JavaScript library

// anonymous user identified before signing in
outbound.identify("12345", {
  attributes : {
    favorite_color : "red",
    favorite_dog : "shiba inu"

// anonymous user id aliased with known id after signing in, and attributes added
outbound.identify("charlie89", {
  firstName: "Charlie",
  lastName: "Young",
  email: "",
  previous_id : "12345",
  attributes : {
    favorite_color : "blue"

In the example, the following combined attributes would be available for campaigns in Outbound:

  • firstName: "Charlie",
  • lastName: "Young",
  • email: "",
  • favorite_color: "blue",
  • favorite_dog: "shiba inu"

Note that favorite_color is "blue" because the request that set the attribute value to blue is more recent.