Segment
Utilize our official Segment integration to manage contacts and send email.
Our Segment integration lets you:
- Create and update contacts
- Send events to trigger loops
Visit our Segment integration to learn more and follow the steps below.
Configuring the destination
After opening the link above, click Configure Loops (Actions).
Select your data source, give the destination a name, and click Create destination.
Next, you’ll need an API key. You can generate a new one for Segment on the Loops API Settings page.
Enter the API key on your Segment destination settings:
Enable the destination and click Save Changes. Note that no data will start flowing until you create specific mappings for Loops.
Mappings
Segment action destinations require that you map specific fields from your source to your destination (in this case Loops). You can set this up by clicking into the Mappings tab and adding a new mapping. Currently we support updating contacts in Loops and sending events into Loops.
Create or update contact
First, select which events to map. Typically for contact creation and updates, the most useful event to map will be “Identify”.
The next step is to load a sample event to help you map fields appropriately.
Contact properties are found in the traits
object.
For this example, we’ll be using this test event:
{
"messageId": "segment-test-message-gt3ds8",
"timestamp": "2023-05-24T17:58:30.352Z",
"type": "identify",
"email": "[email protected]",
"traits": {
"firstName": "Adam",
"favoriteColor": "blue",
"favoriteNumber": 42,
"mailingLists": [
{ "listId": "1234567890", "subscribed": true }
]
},
"userId": "test-user-a5h7xb"
}
When sending a contact’s details to Loops, you must include an Email and a User ID.
We’ve provided some defaults for the mappings, which will show up in the third step, but it is important you review them:
Segment does not provide an interface to provide the names and types for custom fields that you might be using with Loops. In this example, those fields are favoriteColor
and favoriteNumber
. However, these fields can be passed as a dictionary to the Custom Contact Attributes field.
Ensure that the keys and values you provide match the schema you’ve created in your Contact properties settings.
Click Edit Object to specify the custom fields you want to send to Loops individually:
In most cases, you want to leave the Subscribed field as the default (deselected). Setting this to true
will re-subscribe contacts who had previously unsubscribed, and setting it to false
will unsubscribe contacts from receiving email. Leaving it deselected will default new users as subscribed to email and not update the email preference for existing contacts.
After the mappings are configured, send a test event from the fourth step and you should get a successful response:
Check your Loops audience page to ensure the contact was created or updated as intended.
Sending another test event with the same User ID or Email will update the existing contact instead of creating a new contact.
Adding mailing list data
To subscribe contacts to mailing lists there are two options.
By default, we have included mappings for an array called mailingLists
, which includes objects with listId
and subscribed
attributes (see the example test event above).
Alternatively you can edit the Mailing Lists mapping in the UI and enter a hard-coded list ID value. Note that if you choose this option, contacts can only be added to one list due to how the User Mappings UI form handles data.
Send event
You can send events to trigger loops.
First, select which events to map. Typically for sending an event, the most useful event to map will be “Track”. It’s suggested you filter the events down to only ones that you plan on using within Loops using the Event Name filter:
Then after defining or loading a sample event in step 2, configure the mapping. If you want to add event properties, you can pass them as a dictionary to the Event Properties field. Click Edit Object to map the properties to your event property names.
If a contact already exists in your Loops audience, the email field is optional. Loops will trigger based on the User ID. If the contact does not exist in your Loops audience (perhaps you are not using an identify call), you will need to provide an email address otherwise Loops will not be able to create the contact for the event.
After configuring the mapping, you can send a test event in the fourth step and the response should indicate success:
You can verify the event was received on your Events page in Loops.
Sending data to Segment
The following examples use Segment’s Analytics.js library, but the premise is the same for other libraries too.
Create or update contact
For this action you should send a identify()
event. Add contact properties (including any custom properties) in the traits object:
analytics.identify("97980cfea0067", {
email: "[email protected]",
plan: "premium",
logins: 5
});
To add mailing list data, include it in a mailingLists
object like below:
analytics.identify("97980cfea0067", {
email: "[email protected]",
plan: "premium",
logins: 5,
mailingLists: [
{ listId: "cm06f5v0e45nf0ml5754o9cix", subscribed: true },
{ listId: "cm16k73gq014h0mmj5b6jdi9r", subscribed: true }
]
});
Send event
For this action send a track()
event. Data sent in the properties object will be sent as event properties to Loops. Make sure that you have added these event properties in your Events Settings.
analytics.track("User Registered", {
plan: "Pro Annual",
accountType: "Facebook"
});
You have the option to update contacts when sending events by adding contact properties in a context
object.
analytics.track("User Registered", {
plan: "Pro Annual",
accountType: "Facebook",
},
{
traits: {
firstName: "Phil"
}
});