SparkLoop
Search…
Custom Integration
SparkLoop has native, 2-click integrations with 10+ of the most popular email service providers (ESPs). If you have a custom ESP — or if your ESP doesn't have a native integration with SparkLoop yet —

Custom integration requirements

You may be able to integrate your ESP with SparkLoop if we don’t support a native integration. This will require you to complete a small amount of custom development work in building the integration yourself.
Unfortunately, it isn't possible for SparkLoop to build custom integrations for you.

How can I get started?

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
  • updating this data/these custom fields via webhooks you receive from SparkLoop
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
RH_SUBID
SparkLoop's subscriber ID.
RH_CODE
Subscriber's referral code.
RH_REFLINK
Subscriber's referral link.
RH_ISREF
Whether or not the subscriber has been referred. Useful for segmenting.
RH_TOTREF
Subscriber's total number of referrals.
RH_COUPON
Subscriber's most-recently-won coupon code.
RH_LASTREWARD
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

Webhook URL

You can find you webhook URL by going to your Campaign's dashboard > Settings > Notifications page, under Incoming Webhooks.

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:
1
{
2
"type": "subscribe",
3
"subscriber": {
4
"email": "[email protected]",
5
"id": 123, // The subscriber ID in your ESP, optional
6
"first_name": "John", // optional
7
"name": "John Doe", // optional
8
"created_at": 1564400550 // timestamp of the sign up, optional
9
}
10
}
Copied!

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.
1
{
2
"type": "update",
3
"subscriber": {
4
"first_name": "John", // optional
5
"name": "John Doe", // optional
6
"email": "[email protected]",
7
"previous_email": "[email protected]",
8
"updated_at": 1564400550 // optional
9
}
10
}
Copied!

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.
1
{
2
"type": "unsubscribe",
3
"subscriber": {
4
"email": "[email protected]"
5
}
6
}
7
Copied!

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 specify the URL you want to receive the webhook notifications to in the Settings > Notifications page, under Webhook.

Subscriber synced

1
{
2
"type": "sync_subscriber",
3
"campaign_id": "MF6319db9890",
4
"subscriber": {
5
"id": "sub_hjdgc74u", // SparkLoop subscriber ID
6
"first_name": "John",
7
"name": "John Doe",
8
"email": "[email protected]",
9
"referral_code": "ada90f39",
10
"referral_link": "https://mywebsite.com?rh_ref=ada90f39",
11
"referred": true,
12
"tot_referrals": 0, // total number of referrals
13
"last_reward": "reward_38sf38hd", // ID of last reward won
14
"next_reward": 2 // Referrals needed to next reward
15
}
16
}
Copied!

New Referral

1
{
2
"type": "new_referral",
3
"campaign_id": "MF6319db9890",
4
"subscriber": {
5
"id": "sub_hjdgc74u",
6
"first_name": "John",
7
"name": "John Doe",
8
"email": "[email protected]",
9
"referral_code": "ada90f39",
10
"referral_link": "https://mywebsite.com?rh_ref=ada90f39",
11
"referred": true,
12
"tot_referrals": 0,
13
"last_reward": null,
14
"next_reward": 2,
15
"created_at": 1564400550
16
},
17
"referrer": {
18
"id": "sub_93ehus8h",
19
"first_name": "John",
20
"name": "John Smith",
21
"email": "[email protected]",
22
"referral_code": "f9464199",
23
"referral_link": "https://mywebsite.com?rh_ref=f9464199",
24
"referred": false,
25
"tot_referrals": 4,
26
"last_reward": "reward_38sf38hd",
27
"next_reward": 1,
28
"created_at": 1564403873
29
}
30
}
Copied!

Reward unlocked

1
{
2
"type": "reward_unlocked",
3
"campaign_id": "MF6319db9890",
4
"subscriber": {
5
"id": "sub_hjdgc74u",
6
"first_name": "John",
7
"name": "John Doe ",
8
"email": "[email protected]",
9
"referral_code": "f9464199",
10
"referral_link": "https://mywebsite.com?rh_ref=f9464199",
11
"referred": true,
12
"tot_referrals": 4,
13
"last_reward": "reward_cdebf4f013",
14
"next_reward": 2,
15
"created_at": 1564403873
16
},
17
"reward": {
18
"id": "reward_cdebf4f013",
19
"name": "2018 Private Report: State of the Ecommerce",
20
"referrals": 4,
21
"recurring": false
22
}
23
}
Copied!

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

If you choose to import your existing subscribers using a CSV file please follow these instructions.
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.

Last modified 29d ago