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": "[e-mail]",
  "traits": {
    "firstName": "Adam",
    "favoriteColor": "blue",
    "favoriteNumber": 42
  },
  "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:

Custom contact properties

Segment does not provide an interface to provide the names and types for custom contact properties that you might be using with Loops. In our example, those fields are favoriteColor and favoriteNumber.

You can pass contact properties as a dictionary in 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:

Subscribed

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.

Mailing lists

To subscribe contacts to mailing lists there are two options.

The first method is to manually edit the Mailing Lists data. This will allow you to enter list ID values that are the same for every contact.

Click the Edit Object option, then the + Add Mapping Field button. In the Select event variable field enter “true” or “false” (to subscribe or unsubscribe) and in the Enter key name field enter your list ID(s).

You can add multiple lists by clicking on the + Add Mapping Field button again. Make sure the data shown below the fields has the same structure as in the image below.

Another option is to add mailing list data to your Identify call, which will let you dd more dynamic data for each contact. You can test this by adding a mailingLists object to traits in your test event with list IDs as keys and true (to subscribe) or false (to unsubscribe) as values.

{
  "messageId": "segment-test-message-gt3ds8",
  "timestamp": "2023-05-24T17:58:30.352Z",
  "type": "identify",
  "email": "[e-mail]",
  "traits": {
    "firstName": "Adam",
    "favoriteColor": "blue",
    "favoriteNumber": 42,
    "mailingLists": {
      "cm06f5v0e45nf0ml5754o9cix": true,
      "cm16k73gq014h0mmj5b6jdi9r": true,
    }
  },
  "userId": "test-user-a5h7xb"
}

Then you need to map the data. Click the Select Object option, then search for traits.mailingLists from the Event Variables options.

Testing

After the mappings are configured you can preview the data that will be sent.

You can also send a test event to Loops to verify everything is working (this will send actual data to your Loops account). If it works, you will 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.

Send event

You can send events to trigger loops.

First, select which event(s) to map. Typically for sending an event, the most useful event to map will be “Track”.

We recommend that 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.

Required fields

The User ID field is required. If a contact already exists in your Loops audience, the Contact Email field is optional; if the contact does not exist in Loops you need to include an email address so that a contact can be created and an email can be sent (we recommend always including an email address).

Event properties

If you want to add event properties, you can pass them as a dictionary to the Event Properties field. These properties can be included in emails triggered by your event.

You can choose to select the properties object to send all data from the track call. Or if you click Edit Object you can select individual properties. Make sure to enter the correct contact property name from Loops in the Enter key name field.

Contact properties

You can update contacts at the same time as sending an event with the Contact Properties field.

Click Edit Object and specify the properties and values you want to update on your contacts.

Ensure that the keys and values you provide match the schema you’ve created in your Contact properties settings, otherwise some data may not be captured by Loops.

You can choose to add a contact’s email address in the Contact Email field or in the Contact Properties object.

Testing

After configuring the mapping, you can send a test event at the bottom of the page (this will send actual data to your Loops account). You can preview the data that will be sent.

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 show how you can send data from your application to Segment for the two Loops actions.

The examples use Segment’s Analytics.js library, but the premise is similar for other libraries.

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: "[e-mail]",
  plan: "premium",
  logins: 5
});

If you’re mapping a mailingLists object from traits (read more above) add it like this:

analytics.identify("97980cfea0067", {
  email: "[e-mail]",
  plan: "premium",
  logins: 5,
  mailingLists: {
    "cm06f5v0e45nf0ml5754o9cix": true,
    "cm16k73gq014h0mmj5b6jdi9r": 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 in Loops before sending the event to Segment.

analytics.track("User Registered", {
  plan: "Pro Annual",
  accountType: "Facebook",
  firstName: "Phil"
});

You can update a contact’s properties when sending events (for example, firstName) by mapping values in your properties within the Contact Properties object (see above).