Getting Started: Integration Planning

 This document is part of a complete series on Getting Started with

Once you’re familiar with how works, it’s time to start thinking about how to connect your system with ours. Before we discuss how to send your data, we recommend planning out the types of messages you will be sending to your customers. You’ll also want to think about what data you need to personalize, segment, and measure the effectiveness of your messages.

To help you plan your integration, this guide will cover the flow of data to and from We’ll also offer some tips and best practices to help you along the way. You’ll learn about the various ways you can connect your system with later in this series when we discuss Integration Methods.

Workspaces and Profile IDs

It’s important to understand how data is organized in When you signed up, we created an Account for your business. Within each Account, you can create Workspaces.

A workspace is a container for people, campaigns, and messages. Everything you do in, you do from within a workspace. You can have multiple workspaces, all with their own set of people, campaigns, and API credentials.

You have options when it comes to Workspace configurations:

  • Multi-Identifier Workspaces: In a Multi-Identifier Workspace, both email and ID must be unique, but only one is required when creating or updating a Person in This Workspace type is best for managing both pre- and post-signup messages in a single Workspace.
    • If you want to update an email address identifier using the customer’s ID, you must enable the Allow updates to email using ID setting.
  • ID-Based Workspaces: does not enforce uniqueness of the email Attribute in id-based Workspaces. We also do not automatically dedupe email addresses for you. This allows flexibility but may catch you by surprise if you do not take measures on your end to ensure you only have one profile per user. (The only Attribute we require to be unique per Person is id.)
  • Email-Based Workspaces: Email addresses are used as the identifier in an Email-Based Workspace. That means that each profile must have a unique email address.

Learn more about our Workspace configuration options.

Data In and Out

Our system is designed to receive information about your customers and the activities they perform in your systems, as well as send data back to you about People, Campaigns, and Metrics. This allows you to send highly targeted messages in based on that activity. A deliberate approach to mapping your product’s user and behavioral data to is critical for your success. The information you want to use to segment your audience and personalize messages is the data you’ll want to send to

Data In

What to sendDescriptionPurpose
Profile AttributesProperties stored per Person in a Workspace.Send when you want to store data about an individual so you can use it for messaging or segmenting.
EventsActions performed by the People in a Workspace.Send when you want to trigger an Event-triggered Campaign or when you want to log an activity for the purpose of segmenting users by what they've done (or haven't done) in your system.
Page ViewsSpecial events that describe web pages visited by the People in a Workspace.Send when you want to segment People based on pages they have (or haven't) visited on your website.
DevicesThe physical objects used by People in a Workspace to interact with your system.Only required when you send mobile push notifications through
TriggersData sent to trigger specific API Triggered Broadcasts.Only required when using API Triggered Broadcasts to send messages through

Data Out

Methods for getting dataDescriptionPurpose
App APIVarious data about Customers (People), Campaigns, Newsletter Broadcasts, Segments, Message Templates, Messages (Deliveries),Exports, Activities, Sender Identities, trigger API Triggered Broadcasts, send Transactional messages.Retrieve data from your Account and Workspaces for custom reporting in your Business Intelligence tools. Trigger transactional messages and programmatic Broadcasts.
Reporting WebhooksData about select events in real time. For example, email clicks, email opens etc.Set up an endpoint we can use to send information about events as they occur in real time.
CSV exportData for People, Segments, Campaign Metrics and Delivery Logs.Export CSV files containing data about a single Person, many People, Campaign Metrics and Delivery Logs.
Workflow Webhook ActionsData that is sent by your Campaign Workflow or Broadcast.Add a Webhook in any of your Campaign Workflows or Broadcasts to send and receive data from any public API you choose.
Data Warehouse SyncExport bulk historical and real-time data from to your data warehouse.Sync all of your historical and future data to a Data Warehouse, so that you can take advantage of a complete, up-to-date data set in your data warehouse or CRM.

Best Practices

  • Not every database field in your system needs to be in Consider limiting the data you send to to what you need for messaging and segmentation purposes. Anything more than that could make it difficult for your team to understand which data to use. Taking a conservative approach to your data plan ensures a great experience when using
  • You should not send us sensitive, personal information. This includes bank account information, personal health details, credit card numbers, or other secure details. This type of information should not be used directly in email or other types of messages due to their sensitive nature.
  • API limits apply even when your data is being sent by third-party services like and Zapier.

Deep Dive: Data In

Profile Attributes

Profile Attributes are properties stored on a customer’s profile. While there are a few reserved attributes, you can send any data you like. Attributes are named values you use in various places throughout If you want to customize your messages using data that is unique to each Person, you should store that data as Attributes on their profile.

Required Attributes

id or email are the only required attributes depending on the type of Workspace that you configured. All new Workspaces are Multi-Identifier by default, and only one of those identifiers are required to create or update a profile. We also generate a special identifier called cio_id that you can use to update a person’s other identifiers. Read more about updating identifiers.

Reserved Attributes (also optional, but recommended)

You can name your optional Attributes anything you want, but there are a handful of reserved Attribute names that we recommend you use. The following Attributes have special meaning in and may be used in a special way in your account:

  • created_at (lower case) The created_at Attribute should hold a Unix timestamp/Epoch time format value (in seconds) equal to when the Person was created in your system
  • unsubscribed (lower case) Global unsubscribes in are managed using the unsubscribed Attribute value.  The unsubscribed Attribute should be assigned a value of “true” for anyone that is to be treated as unsubscribed from all messaging. Learn more about how we use the unsubscribed Attribute and learn how to manage granular subscription preferences with our subscription center.
  • email (lower case) If you plan to use the Email Action, your profiles must have a valid email address stored in their profile. You are welcome to use a different Attribute name for email addresses. Just be aware that the default Attribute we use across is email. You will need to override our default where possible.
  • phone (lower case) If you plan to use the Twilio Action, your profiles must have a phone number stored in their profile. The default Attribute we use in the message editor is phone but your Attribute could be named something like phone_number or mobile_phone instead.
  • timezone (lower case) Sending us this Attribute will allow you to enable the Time Zone Match feature.
  • named_user This reserved attribute for Airship Actions is no longer available for new customers, but relates to the named_user value in Airship.

Optional Attributes

Profile Attributes are a great place to store data you want to use to personalize the messages you send from Consider adding personal information like first_name, last_name, plan_name or last_login_date as well.

Attributes: Tips and Best Practices

  • Use lowercase letters for your Attribute names. Attribute names are case-sensitive so id, ID and Id are all different Attributes in

  • Avoid attribute names that contain spaces. This will allow you to use Liquid code in your content like {{ customer.first_name }} instead of having to remember that Attributes with spaces must be used like {{ customer["first name"] }} instead. 

  • Use only alphanumeric characters for your Attribute names. Non-alphanumeric characters can cause odd issues that are hard to spot. If you use non-alphanumeric characters in attributes, you’ll have to treat them differently from standard alphanumeric attribute names when referencing attributes using Liquid code in your content.

    For example, if your attributes are address.street or $street, you cannot reference them in standard liquid syntax as {{customer.address.street}} or {{customer.$street}}.

    You would have to use {{customer["address.street"]}} or {{customer["$street"]}} instead.

  • Use properly formatted timestamps. For maximum segmentation options, it is critical that you send timestamp values to in the correct format. (Such as when using the created_at Attribute mentioned above.) If you aren’t familiar with the Unix timestamp/Epoch time format, please review our timestamp FAQ.

  • Validate email addresses and phone numbers before sending them to Check for common input errors like “” or phone numbers that do not have enough digits.

  • Ensure phone numbers are stored in E.164 format: [+][country code][subscriber number including area code]. This is good practice in general, but it is required when used in Twilio Actions. 

  • Stick within the limits. There’s no limit on the number of Attributes you can store in each profile. However, to help us guarantee your account’s reliability and performance, we do have limits in place for the amount of data that can be stored per Attribute.

  • Format the data based on its intended use. Attributes can be a string, boolean or a number.

    • Use booleans, not strings for state:
      • Good: account_manager: true
      • Bad: account_manager: 'true'
    • Numbers should be passed as numbers, not strings:
      • Good: num_projects: 15
      • Bad: num_projects: '15'

Attributes: Practical Examples

Here are some examples of what you can do once you have data in your Peoples’ profile Attributes:

  • Segmentation - If you store a Person’s subscription plan as an Attribute (e.g., free/basic/premium), you can create Segments to match specific subscriber types. With Segments like that you can ensure certain messages only get sent to People who have subscribed to a particular plan. (E.g., subscription_plan: premium)
  • Messaging - If you store a Person’s birthday as an Attribute, you can send them a message every year on their birthday. You can create Campaigns that trigger based on any date stored as an Attribute.
  • Customization - If you store Attributes like first_name, you can personalize messages by displaying the Person’s name in the subject or body using Liquid.
  • Accommodation - If you store a Person’s preferred contact method as “SMS”, you can use that attribute to ensure you send them SMS messages instead of email messages.


Events are actions people perform in your app, on your website, etc—things like button clicks, scrolling to the bottom of a page, or purchases. When you send us events, you can start campaigns and segment your users based on the things they do (or don’t do) in your app.

Consider a streaming music service. Examples of events users perform include:

  • create_playlist
  • play
  • upgrade
  • skip_song
  • star_song
  • search

Track activities that users perform to derive value or enjoyment from your service. It’s less productive to track generic, non-descriptive activities like button clicks. Instead, send in user activity that maps to specific, meaningful behavioral goals.

Events: Practical Examples

Here are some examples of what you can do once you start sending Events to

  • Timely Messaging - If you send an event that describes a purchase that a Person just made in your system, you can send them a receipt with an upsell offer right away while you are still on their mind.
  • Segmentation - If you send an event every time someone achieves a goal in your app, you can create a Segment that matches People who have done that event six times in the last month. With a Segment like that you can send a targeted message to your most engaged users.
  • Intervention - If you send an event every time someone submits a support request, you can send a Slack message to your team for someone to investigate when the same Person has submitted more than three requests in a week.

Events: Tips and Best Practices

  • Use only alphanumeric characters for your Event names. *, +, and | characters are not supported in event names. If you attempt to use them anyway, you may experience issues that are hard to spot. For example, using "have performed the event event1|event2" in your segment criteria will be interpreted as "have performed the event 'event1' OR 'event2'". There currently is no way to escape these characters in your segment criteria order to find events with names that have those characters in them. If you must separate words, we recommend using underscores _.
  • Track activities that users perform to derive value or enjoyment from your service. It’s less productive to track generic, non-descriptive activities like button clicks. Instead, send in user activity that maps to specific, meaningful behavioral goals.
  • Use a simple naming convention that is readable, easy to understand, and corresponds to the activity you are tracking.
  • If you send an Event using a profile id that doesn’t exist in your account, a new Person will be created using the profile id sent with the Event. That profile will not have any Attributes (other than id) until you send them separately.
  • Historical event data should include the timestamp when the event originally occurred. If the timestamp is not included, will interpret the event as occurring at the time the event is sent.


    Please be aware that backfilling event data may trigger campaigns or messages, if those events are used as triggers!

    • A backdated event WILL trigger event-triggered campaigns if the event’s timestamp is within the last 3 days (72 hours).
    • A backdated event WILL NOT trigger event-triggered campaigns if the event’s timestamp is older than 3 days (72 hours).

Event Attributes

Just as profile Attributes (above) describe People, the Event Attributes you send in your Events describe each instance of the Event. Event Attributes are not required but sending them will make your Events more valuable. Event Attributes can be used to create Segments and to customize the messages you send in any Campaign that is triggered by your Event.

For example, you could send the following Event and Event Attribute data:

  • Event Name (the action taken by the user):
    • enrolled
  • Event Attributes (data describing each instance of the Event):
    • course_title
    • course_fee
    • course_instructor
    • course_url
    • course_img_url

With an Event like that you can create Segments like “Has enrolled in any course”, “Has enrolled in Pigeon Calling 101” or “Has never been taught by Jane Smith”. Additionally, when you trigger a Campaign using this Event, you will be able to include any of the Event Attribute values in messages you send from your Event-triggered Campaigns. This is done using Liquid code in your content like, {{ event.course_instructor }}.

Event Attributes: Tips and Best Practices

  • For Event Attributes, we recommend you use the same best practices as described above for profile Attributes.
  • There’s no limit on the number of Event Attributes you can send with each Event. However, we do have limits in place for the overall size of the event data.
  • Event Attributes are only accessible when configuring Segment conditions and in messages sent by Event-triggered Campaigns. They cannot be accessed in Broadcasts, Segment-triggered Campaign content, or Date-triggered Campaign content.
  • Event Attributes should not contain profile Attribute data. The Event will be tied to the user profile.
  • Event Attributes are stored with the Event. They do not change and they do not automatically become profile Attributes as they are meant to describe the Event, not the Person. Event Attribute data can be added to a Person’s profile as part of Campaign’s workflow if desired.

Page Views

Send us data about the pages your People view so you can build useful Segments using that data. This is done using our JavaScript snippet or our API.

Page Views: Practical Examples

Here are some examples of what you can do once you start sending Page Views to

  • Monitor - You can create a Segment to match People who keep viewing your best selling products but haven’t made a purchase yet. Then you can optionally message them about an upcoming promotion for the item they’ve been looking at.
  • Classify - Have topical articles? You can create a Segment to match People who viewed an article about “Game of Thrones.” Then you can use that Segment to trigger a Campaign that will update their profile to reflect that interest.

Page Views: Tips and Best Practices

  • If you don’t need Segments related to Page Views, feel free to skip this part of the integration planning.
  • Avoid sending Page View Events for users who are not logged into your system and already known to Sending Page Views for unknown users will create unusable Page View data in your account that is not assigned to any of your profiles. There will be no way for you to access or use this information.
  • You can build Segments based on full URL paths or use wildcards for partial URL matching.


If you plan to use to send push notifications via our native push feature (as opposed to using webhooks) then you will need to send us IDs for the Devices your People use. Device data is sent to us using our API. Our SDKs provide a ready-made integration to identify people who use mobile devices and send them notifications.

Devices: Practical Examples

Here are some examples of what you can do once you start sending Devices to

  • Alert - Send People urgent push notifications based on their current location.
  • Inform - Let People know about major app updates nudge them to install the new version or check out a new feature. 
  • Remind - Send People reminders to complete key actions in your app.

Devices: Tips and Best Practices

  • Typically, Device IDs should be sent every time the app is launched on a client Device. Our recommendation is to integrate your mobile app by installing our native mobile SDKs.
  • We only store 25 Devices per customer. If a Person already has 25 Devices when a new Device is being added, we remove the Device with the oldest last_used timestamp and add the new Device.
  • By default, your push notification will go to all devices associated with a particular Person.
  • When testing your push configuration and messages for quality assurance (QA) purposes, we recommend that you use separate development/test and production Workspaces—especially if you need to use separate configuration credentials.

API Triggered Broadcast Data

Using API Triggered Broadcasts is a two step process. First, you set up an API Triggered Broadcast in Then you configure your system to send the data that will trigger the Broadcast via our API.

API Triggered Broadcasts: Practical Examples

Here are some examples of what you can do once you set up API Triggered Broadcasts and start sending trigger data to

  • Topical Updates - Send an announcement to People about subjects they care about. Imagine two announcements using the same message templates: “Game of Thrones reboot already underway.” and “Stranger Things actors on strike over script mishap.”
  • Location-based Alerts - Notify People when an incident occurs in a location they care about. Imagine one configuration that can send both: “Mapletown’s Fall Festival dates updated to October 29-30.” and “Power out in much of Manhattan.”

API Triggered Broadcasts: Tips and Best Practices

  • When you trigger an API Triggered Broadcast, each trigger can have its own (optional) set of JSON data. JSON is simply the way the data is formatted. It stands for JavaScript Object Notation. Learn more in our documentation about formatting Broadcast data.
  • Be mindful of the limits we’ve put in place when sending API Triggered Broadcast data.
  • Trigger data has no effect on profile Attributes. Once sent, trigger data cannot be changed. Also, it does not automatically update a Person’s profile Attributes because it is only meant to provide data for the messages being sent. Trigger data can be added to a Person’s profile as part of Broadcast’s workflow if desired.
  • The data in a trigger is only accessible within that Broadcast’s individual messages.

Deep Dive: Data out

You can also pull data from for whatever external purposes your organization requires. Here’s a general overview of the kind of data you can get from

Practical Examples

  • Generate custom reports by exporting Delivery Logs from your account and processing them in your favorite third-party analytics tool.
  • Use our API to pull the ids for everyone belonging to key Segments.
  • Get Webhook notifications so you can learn about email failures quickly and investigate.


Our App API allows you to selectively pull data from your account. It is a collection of endpoints that includes customer and message data such as attributes, segments, campaigns, collections, experts, messages (sent, delivered, bounced, etc).

Learn more about the App API in our API docs.

Reporting Webhooks

We can optionally send real-time data about a select set of activities to any public endpoint you choose. Once your team has such an endpoint ready to receive data, it’s as simple as adding that endpoint to your Workspace configuration in

Learn more by viewing our Email Webhook documentation.

CSV export

You can export data from within the user interface (UI) any time you are logged into your account. Generally speaking, the option to export is shown as a button or menu item located at the upper-right corner of whatever page or page section you are working in. Exporting data will result in downloadable CSV files containing data about a single Person, many People, Campaign Metrics or Delivery Logs.

Workflow Webhook Actions

We can optionally send real-time data about a select set of activities to any public endpoint you choose. Once your team has such an endpoint ready to receive data, it’s as simple as adding that endpoint to your Workspace configuration in

Learn more by viewing our Webhook Actions documentation.

Data Warehouse Sync

Round out your internal reporting with the most complete set of data using Data Warehouse Sync. Every 15 minutes you’ll receive rich data about messages, people, metrics, and more in your Amazon Web Services (AWS) or Google Cloud Project (GCP) cloud storage bucket. From there, you can load the data into the data store of your choice for in-depth analysis.

Learn more by viewing our Data Warehouse Sync documentation.

Copied to clipboard!