SparkLoop’s 2-click integration works with most ESPs.
However, if you have a custom ESP or if SparkLoop doesn’t support your ESP yet, you can build a custom integration yourself using the steps below.
This will require a small amount of custom development work.
⚠️ SparkLoop's custom integration is only available for customers on our Media Brand annual plan.
Custom integration requirements
Custom integrations are currently invite-only and require a concierge or annual package.
To request access and get more info from our integrations team, please contact us here.
Can my ESP support a custom SparkLoop integration?
In order to build a custom SparkLoop integration, your ESP must support the following functionalities:
storing data unique to each email contact (eg as custom fields or custom attributes)
dynamically inserting this data into the email body
update this data/these custom fields
Additionally, you must be able to:
send webhooks to SparkLoop when certain events happen in your ESP
receive webhooks from SparkLoop and process the data
Custom fields
When your subscribers are synced with SparkLoop, we will generate a bunch of data (like the referral link) that needs to be stored in your ESP, usually in custom fields.
Here's a list of the custom fields we recommend creating and their meaning:
NAME | Description |
| SparkLoop's subscriber ID. |
| Subscriber's referral code. |
| Subscriber's referral link. |
| Whether or not the subscriber has been referred. Useful for segmenting. |
| Subscriber's total number of referrals. |
| Subscriber's most-recently-won coupon code. |
| The ID of the last reward won by this subscriber. |
Flows diagram
In the diagram below you can see how your integration should interact with SparkLoop for the three most common events: when a person signs up to your list, when a person refers a friend and when a person unlocks a reward.
Sending data TO SparkLoop
You must notify SparkLoop via webhooks when certain events happen:
when a new person signs up
(optional) when an existing contact updates their email address
(optional) when an existing contact unsubscribes
Incoming Webhook URL
You can find you incoming webhook URL by going to your Integrations page.
New signup
⚠️ If you use double opt-in please send this webhook AFTER they confirm their email address.
When a new person signs up to your email list you must send SparkLoop a webhook notification with the following payload:
{
"type": "subscribe",
"subscriber": {
"email": "john.doe@email.com",
"id": 123, // The subscriber ID in your ESP, optional
"first_name": "John", // optional
"name": "John Doe", // optional
"created_at": 1564400550 // timestamp of the sign up, optional
}
}
Subscriber updated (optional)
When an existing subscriber changes their email address you should send SparkLoop a webhook notification with the following payload.
While this event is optional it is HIGHLY recommended as SparkLoop uses email addresses to identify subscribers.
{
"type": "update",
"subscriber": {
"first_name": "John", // optional
"name": "John Doe", // optional
"email": "john.doe@email.com",
"previous_email": "john.doe.previous@email.com",
"updated_at": 1564400550 // optional
}
}
Subscriber unsubscribes (optional)
When an existing subscriber unsubscribes you should send SparkLoop a webhook notification with the following payload.
While this event is optional it is HIGHLY recommended as SparkLoop charges you based on the number of active subscribers.
{
"type": "unsubscribe",
"subscriber": {
"email": "john.doe@email.com"
}
}
Receiving data FROM SparkLoop
SparkLoop will send you webhooks notifications in response to certain events:
when a new subscriber is synced with SparkLoop (when SparkLoop generates the referral link and the other data)
when a subscriber gets a new referral
when a subscriber unlocks a milestone reward
Webhook URL
You can create a webhook to receive the notifications by going to Settings > Integrations > Webhooks.
Make sure to select at least the "Subscriber Created or Updated" event, but ideally all three.
Subscriber synced
{
"type": "sync_subscriber",
"campaign_id": "MF6319db9890",
"subscriber": {
"id": "sub_hjdgc74u", // SparkLoop subscriber ID
"first_name": "John",
"name": "John Doe",
"email": "john.doe@email.com",
"referral_code": "ada90f39",
"referral_link": "https://mywebsite.com?rh_ref=ada90f39",
"referred": true,
"tot_referrals": 0, // total number of referrals
"last_reward": "reward_38sf38hd", // ID of last reward won
"next_reward": 2 // Referrals needed to next reward
}
}
New Referral
{
"type": "new_referral",
"campaign_id": "MF6319db9890",
"subscriber": {
"id": "sub_hjdgc74u",
"first_name": "John",
"name": "John Doe",
"email": "john.doe@email.com",
"referral_code": "ada90f39",
"referral_link": "https://mywebsite.com?rh_ref=ada90f39",
"referred": true,
"tot_referrals": 0,
"last_reward": null,
"next_reward": 2,
"created_at": 1564400550
},
"referrer": {
"id": "sub_93ehus8h",
"first_name": "John",
"name": "John Smith",
"email": "john.smith@email.com",
"referral_code": "f9464199",
"referral_link": "https://mywebsite.com?rh_ref=f9464199",
"referred": false,
"tot_referrals": 4,
"last_reward": "reward_38sf38hd",
"next_reward": 1,
"created_at": 1564403873
}
}
Reward unlocked
{
"type": "reward_unlocked",
"campaign_id": "MF6319db9890",
"subscriber": {
"id": "sub_hjdgc74u",
"first_name": "John",
"name": "John Doe ",
"email": "john.doe@email.com",
"referral_code": "f9464199",
"referral_link": "https://mywebsite.com?rh_ref=f9464199",
"referred": true,
"tot_referrals": 4,
"last_reward": "reward_cdebf4f013",
"next_reward": 2,
"created_at": 1564403873
},
"reward": {
"id": "reward_cdebf4f013",
"name": "2018 Private Report: State of the Ecommerce",
"referrals": 4,
"recurring": false
}
}
Importing existing subscribers in SparkLoop
When you create a referral program in SparkLoop you will need to generate a referral link for your existing subscribers. You have two options:
import your subscribers via a CSV file
import your subscribers via our APIs
CSV file
SparkLoop will automatically generate a referral link for each subscriber and fire off a sync_subscriber event you can use to store the referral link in your ESP.
APIs
If you choose to import your existing subscribers using our APIs you can find the API endpoint here.
Webhooks retries
If our webhooks notifications fail to deliver we will retry for up to a month with exponential back-off.
We expect your webhooks to do the same and be retried at least a few times when they fail.