Reference Guides
Integrations
Versioning
Segment
Connecting Segment to Poplar
Use Segment to trigger a mailing, share order data, or add an audience member to a list in Poplar with custom Destination Functions. There are two primary ways to send a destination function to Poplar within Segment:
- Directly from a Source
- Sharing Order Data for In-Platform Reporting
- Triggering Mailings
- Adding Members to an Audience or Do Not Mail List
Step 1: Connections
Start by navigating to the Connections tab within your Segment account:
On the left you'll see a list of your data Sources and the option to + Add Source, and on the right you'll see a list of your Destinations and the option to + Add Destination.
If it's not already listed, add the Source from where you'll be pulling mailing data and make sure it's Enabled for use.
Step 2: Destination
Once your Source is established, click Add Destination to view the Destination options under the Catalog section. To integrate with Poplar, you'll need to build a custom function that triggers a mailing when an event occurs.
Navigate to the Functions tab and click + New Function to begin:
Select Destination as the Function Type, then Build:
Step 3: Build
Before editing code, you'll need to configure the behavior of your function by adding Settings. Settings are used for encrypting your Authorization credentials (API Access Tokens) and they allow you to pass variables such as
campaign_id, creative_id, and audience_id to your function. There are a number of ways Segment can integrate with Poplar's APIs:
- Trigger a mailing
- Share order data for in-platform reporting
- Update an existing audience list
- Update your Do Not Mail list
Settings
Head to the Settings tab and click + Add Setting. Each use case listed above requires different Setting which should be defined in the following ways:
Mailing
Orders
Audiences
Do Not Mail
Authorization
First you'll want to configure the variable for your Test or Production Access Token. Make sure both Required and Encrypted are enabled, the encryption setting will ensure your access token stays secret.
Campaign ID
Create another Setting for your
campaign_id. Campaign ID can be found in your Poplar account under your campaign's Overview tab. This value does not need to be Encrypted.
Creative ID (Optional)
Creative ID can be specified if more than one creative is active under the campaign, and you want to specifically point to one. Click into a creative to find the
creative_id. If creative_id is not specified, the trigger will point to the Default active creative. If no creative is set as the default, it equally rotate between mailing all active creatives under the campaign to A/B Test.
Authorization
First you'll want to configure the variable for your Production Access Token. Make sure both Required and Encrypted are enabled, the encryption setting will ensure your access token stays secret.
Authorization
First you'll want to configure the variable for your Production Access Token. Make sure both Required and Encrypted are enabled, the encryption setting will ensure your access token stays secret.
Audience ID
To add an audience member to a list, the audience must first be created in Poplar. Click into an existing Audience to find the
audience_id.
Authorization
First you'll want to configure the variable for your Production Access Token. Make sure both Required and Encrypted are enabled, the encryption setting will ensure your access token stays secret.
Step 4: Source Code
Now that you've established Settings, you can begin coding your function. Segment invokes a separate part of the function (called a “handler”) for each event type. Destination functions can define handlers for each message type in the Segment spec:
onIdentifyonTrackonPageonScreenonGrouponAliasonDeleteonBatch
Each of the functions above accepts two arguments:
- event - Segment event object, where fields and values depend on the event type. For example, in “Identify” events, Segment formats the object to match the Identify spec.
Just like Settings, different source code is required based on use case. Below are code templates that can be copy & pasted in place of any existing source code:
Our examples show a destination function that listens for “Track” events, and sends certain data to Poplar by using the
event.properties prefix. This prefix will likely differ by case depending on how your data is structured.Mailing
Orders
Audiences
Do Not Mail
To create a mailing, you'll want to send a
POST request to https://api.heypoplar.com/v1/mailing
Your headers should contain Authorization: `Bearer ${settings.apiKey}`, and 'Content-Type': 'application/json'Address and/or Email Data
1
/**
2
* @param {SpecTrack} event The track event
3
* @param {Object.<string, any>} settings Custom settings
4
* @return any
5
*/
6
async function onTrack(event, settings) {
7
const body = {
8
campaign_id: `${settings.campaignId}`,
9
recipient: {
10
full_name: event.properties.full_name,
11
address_1: event.properties.address_1,
12
address_2: event.properties.address_2,
13
city: event.properties.city,
14
state: event.properties.state,
15
postal_code: event.properties.postal_code,
16
email: event.properties.email
17
}
18
};
19
20
const response = await fetch('https://api.heypoplar.com/v1/mailing', {
21
method: 'POST',
22
headers: {
23
Authorization: `Bearer ${settings.apiKey}`,
24
'Content-Type': 'application/json'
25
},
26
body: JSON.stringify(body)
27
});
28
29
return response.json();
30
}
Copied!
Custom Merge Tags
1
/**
2
* @param {SpecTrack} event The track event
3
* @param {Object.<string, any>} settings Custom settings
4
* @return any
5
*/
6
async function onTrack(event, settings) {
7
const body = {
8
campaign_id: `${settings.campaignId}`,
9
recipient: {
10
full_name: event.properties.full_name,
11
address_1: event.properties.address_1,
12
address_2: event.properties.address_2,
13
city: event.properties.city,
14
state: event.properties.state,
15
postal_code: event.properties.postal_code,
16
email: event.properties.email
17
},
18
merge_tags: {
19
promo-code: event.properties.code
20
}
21
};
22
23
const response = await fetch('https://api.heypoplar.com/v1/mailing', {
24
method: 'POST',
25
headers: {
26
Authorization: `Bearer ${settings.apiKey}`,
27
'Content-Type': 'application/json'
28
},
29
body: JSON.stringify(body)
30
});
31
32
return response.json();
33
}
Copied!
To share order data, you'll want to send a
POST request to https://api.heypoplar.com/v1/order
Your headers should contain Authorization: `Bearer ${settings.apiKey}`, and 'Content-Type': 'application/json'1
/**
2
* @param {SpecTrack} event The track event
3
* @param {Object.<string, any>} settings Custom settings
4
* @return any
5
*/
6
async function onTrack(event, settings) {
7
const body = {
8
email: event.properties.email,
9
identifier: event.properties.identifier,
10
shipping_address: {
11
name: event.properties.full_name,
12
address_1: event.properties.address_1,
13
address_2: event.properties.address_2,
14
city: event.properties.city,
15
state: event.properties.state,
16
postal_code: event.properties.postal_code
17
},
18
order_id: event.properties.order_id,
19
total: event.properties.order_total,
20
order_date: event.receivedAt
21
};
22
23
const response = await fetch('https://api.heypoplar.com/v1/order', {
24
method: 'POST',
25
headers: {
26
Authorization: `Bearer ${settings.poplarApiKey}`,
27
'Content-Type': 'application/json'
28
},
29
body: JSON.stringify(body)
30
});
31
32
return response.json();
33
}
Copied!
shipping_address and/or billing_address may be used when passing order data. For more details on required and optional values, see our Orders API.To add an audience member to a list, you'll want to send a
POST request to https://api.heypoplar.com/v1/audiences/${settings.audienceID}
Your headers should contain Authorization: `Bearer ${settings.apiKey}`, and 'Content-Type': 'application/json'1
/**
2
* @param {SpecTrack} event The track event
3
* @param {Object.<string, any>} settings Custom settings
4
* @return any
5
*/
6
async function onTrack(event, settings) {
7
const body = {
8
address: {
9
name: event.properties.full_name,
10
address_1: event.properties.address_1,
11
address_2: event.properties.address_2,
12
city: event.properties.city,
13
state: event.properties.state,
14
postal_code: event.properties.postal_code
15
},
16
email: event.properties.email,
17
identifier: event.properties.identifier
18
};
19
20
const response = await fetch(
21
`https://api.heypoplar.com/v1/audience/${settings.audienceId}`,
22
{
23
method: 'POST',
24
headers: {
25
Authorization: `Bearer ${settings.apiKey}`,
26
'Content-Type': 'application/json'
27
},
28
body: JSON.stringify(body)
29
}
30
);
31
32
return response.json();
33
}
Copied!
To add a member to your Do Not Mail list, you'll want to send a
POST request to https://api.heypoplar.com/v1/do-not-mail
Your headers should contain Authorization: `Bearer ${settings.apiKey}`, and 'Content-Type': 'application/json'1
/**
2
* @param {SpecTrack} event The track event
3
* @param {Object.<string, any>} settings Custom settings
4
* @return any
5
*/
6
async function onIdentify(event, settings) {
7
const body = {
8
email: event.traits.email,
9
identifier: event.traits.identifier,
10
address: {
11
name: event.traits.full_name,
12
address_1: event.traits.address_1,
13
address_2: event.traits.address_2,
14
city: event.traits.city,
15
state: event.traits.state,
16
postal_code: event.traits.postal_code
17
}
18
};
19
20
const response = await fetch('https://api.heypoplar.com/v1/do-not-mail', {
21
method: 'POST',
22
headers: {
23
Authorization: `Bearer ${settings.apiKey}`,
24
'Content-Type': 'application/json'
25
},
26
body: JSON.stringify(body)
27
});
28
29
return response.json();
30
}
Copied!
Step 5: Run
To run your function, you'll need to select a sample event from your Source. Make sure the sample event contains all the necessary data for mailing.
Use Sample Event
On the right under the Test tab, click Use Sample Event to select your source and event for testing:
.gif?alt=media&token=b68bab85-1b90-4a2f-ac3c-75c10bd975b9)
You'll then be prompted to enter values for the API Key and CampaignID settings. Enter the values and hit Run in the top right to send a test trigger.
We strongly recommend you use the Test token provided in the API section of your Poplar account, to ensure your trigger is set up successfully. After you see it working, swap it out for the Production token which will set the trigger live.
History Tab
Head to the History tab of your campaign within your Poplar account to see successful tests come through:
Click into one of the mailers to see a PDF proof with the user data applied. Scroll down to the Request Details to confirm the data coming through the platform matches your function.
If using custom merge tags, make sure they are properly located within the merge_tags object in your Request Details.
Step 6: Save & Deploy
Once you've confirmed the integration is successful, hit the Configure button in the bottom right to Configure & Create your function.
Step 7: Connect Destination!
Journeys are a feature of Segment Personas. They provide ways to personalize experiences or workflows through planning how and when to engage customers with the right campaigns and messages. Learn how to use your Destination Function in a Journey to trigger mailings or add members to an Audience or Do Not Mail list.
To connect directly to a source without using Journeys, click the + Connect Destination button and select your Source. Make sure you've entered your Production API Key, then hit Confirm Source and turn on your function:
Last modified 5mo ago