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

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

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": "[email protected]",
"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": "[email protected]",
"previous_email": "[email protected]",
"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": "[email protected]"
}
}


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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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": "[email protected]",
"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.

Did this answer your question?