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

• Via a Journey that is a constantly updated user segment/filter

  • 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:

Destination Functions

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

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.

Orders

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.

Audiences

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.

Do Not Mail

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:

• onIdentify

• onTrack

• onPage

• onScreen

• onGroup

• onAlias

• onDelete

• onBatch

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.

• settings - Set of settings for this function.

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

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

This function can be used for both full address data or emails for Address Enrichment.

/**
 * @param {SpecTrack} event The track event
 * @param {Object.<string, any>} settings Custom settings
 * @return any
 */
async function onTrack(event, settings) {
	const body = {
		campaign_id: `${settings.campaignId}`,
		recipient: {
			full_name: event.properties.full_name,
			address_1: event.properties.address_1,
			address_2: event.properties.address_2,
			city: event.properties.city,
			state: event.properties.state,
			postal_code: event.properties.postal_code,
			email: event.properties.email
		}
	};

	const response = await fetch('https://api.heypoplar.com/v1/mailing', {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${settings.apiKey}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify(body)
	});

	return response.json();
}

Custom Merge Tags

If your creative uses custom merge tags, be sure to include the merge_tags object.

/**
 * @param {SpecTrack} event The track event
 * @param {Object.<string, any>} settings Custom settings
 * @return any
 */
async function onTrack(event, settings) {
	const body = {
		campaign_id: `${settings.campaignId}`,
		recipient: {
			full_name: event.properties.full_name,
			address_1: event.properties.address_1,
			address_2: event.properties.address_2,
			city: event.properties.city,
			state: event.properties.state,
			postal_code: event.properties.postal_code,
			email: event.properties.email
		},
    merge_tags: {
      promo-code: event.properties.code
    }
	};

	const response = await fetch('https://api.heypoplar.com/v1/mailing', {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${settings.apiKey}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify(body)
	});

	return response.json();
}

Orders

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'

/**
 * @param {SpecTrack} event The track event
 * @param {Object.<string, any>} settings Custom settings
 * @return any
 */
async function onTrack(event, settings) {
	const body = {
		email: event.properties.email,
		identifier: event.properties.identifier,
		shipping_address: {
			name: event.properties.full_name,
			address_1: event.properties.address_1,
			address_2: event.properties.address_2,
			city: event.properties.city,
			state: event.properties.state,
			postal_code: event.properties.postal_code
		},
		order_id: event.properties.order_id,
		total: event.properties.order_total,
		order_date: event.receivedAt
	};

	const response = await fetch('https://api.heypoplar.com/v1/order', {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${settings.poplarApiKey}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify(body)
	});

	return response.json();
}

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.

Audiences

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'

/**
 * @param {SpecTrack} event The track event
 * @param {Object.<string, any>} settings Custom settings
 * @return any
 */
async function onTrack(event, settings) {
	const body = {
		address: {
			name: event.properties.full_name,
			address_1: event.properties.address_1,
			address_2: event.properties.address_2,
			city: event.properties.city,
			state: event.properties.state,
			postal_code: event.properties.postal_code
		},
		email: event.properties.email,
		identifier: event.properties.identifier
	};

	const response = await fetch(
		`https://api.heypoplar.com/v1/audience/${settings.audienceId}`,
		{
			method: 'POST',
			headers: {
				Authorization: `Bearer ${settings.apiKey}`,
				'Content-Type': 'application/json'
			},
			body: JSON.stringify(body)
		}
	);

	return response.json();
}

For more details on required and optional values, see our Audiences API.

Do Not Mail

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'

/**
 * @param {SpecTrack} event The track event
 * @param {Object.<string, any>} settings Custom settings
 * @return any
 */
async function onIdentify(event, settings) {
	const body = {
		email: event.traits.email,
		identifier: event.traits.identifier,
		address: {
			name: event.traits.full_name,
			address_1: event.traits.address_1,
			address_2: event.traits.address_2,
			city: event.traits.city,
			state: event.traits.state,
			postal_code: event.traits.postal_code
		}
	};

	const response = await fetch('https://api.heypoplar.com/v1/do-not-mail', {
		method: 'POST',
		headers: {
			Authorization: `Bearer ${settings.apiKey}`,
			'Content-Type': 'application/json'
		},
		body: JSON.stringify(body)
	});

	return response.json();
}

For more details on required and optional values, see our Do Not Mail API.

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:

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: