SparkLoop’s 2-click integration works with most ESPs.

However, if you have a custom ESP or SparkLoop doesn’t support your ESP yet, you can build a custom integration using the steps below.

If your custom integration only needs to work with Upscribe, then check this other article.

This will require a small amount of custom development work from your side, and we won't be able to provide dev support.

For customized integrations, there are a couple of setup requirements:

Establishing a method to transmit data to SparkLoop: We facilitate this process through the provision of an Incoming Webhook. You must send a webhook notification whenever a subscriber subscribes or unsubscribes from your ESP (Email Service Provider). Without these notifications, we won't be able to track these events.

Implementing a mechanism to receive data from SparkLoop: This involves configuring Webhooks so that we know where to transmit data. For instance, we need to know when a subscriber earns a referral point or achieves a new reward.

For point one, we expect to receive specific event notifications. You'll need to handle our notifications for the second point, with details provided in the same article. It's important to note that you can't customize the data format.

We're not directly sending data to your ESP; we're sending data to the webhook URL you set. Ultimately, deciding how to manage that data is up to you.

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": "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 must 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.