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, you must be able to:
install a small Javascript snippet on your website or landing page
send webhooks to SparkLoop when certain events happen in your ESP
receive webhooks from SparkLoop and process the data
(optional) storing data unique to each email contact (eg as custom fields or custom attributes)
Understanding the flow of events
There are several ways in which a referral can be made: via a form on your website, via Upscribe, Magic links, etc.
When the referral signs up on a form on your website, this is what the flow of events looks like:
A person signs up on your website. Our script, installed on your website, tracks that sign-up automatically.
You send SparkLoop a "subscribe" event to confirm the sign-up. (If you use double opt-in, you must send this event AFTER they confirm their email address)
SparkLoop sends you the first "sync_subscriber" webhook event. In this event, the subscriber has not been processed yet.
As soon as the subscriber is processed, SparkLoop runs a referral assignment process that includes checking for fraudulent referrals, the email's validity, etc. Based on that process, SparkLoop assigns a referral status and informs you again about it via a "sync_subscriber" webhook event.
When the number of days set by you in the "screening period" (ie how many days they have to be subscribed to count as active) have passed, SparkLoop checks the status of the subscriber one last time. If they are still subscribed to your email list, it sends you a "new_partner_referral" webhook event to confirm the referral.
Until you receive a "new_partner_referral" webhook event from SparkLoop about a referral, you should assume they are not confirmed as a referral.
If the subscriber unsubscribes at any point, or if you want to disqualify them for any reason (ie they haven't opened the emails you send them), you must send SparkLoop a "unsubscribe" event. In the absence of this event, SparkLoop will confirm the referral and count them towards your budget (unless they have been rejected for other reasons, i.e., anti-fraud).
When the referral comes from Upscribe or a Magic link, this is what the flow of events looks like:
SparkLoop sends you a "sync_subscriber" event with the referral information. If the subscriber has been rejected, for example, by our antifraud, the
referral_statuswill be set to "rejected". Otherwise, it will be set to "pending".You add the referral to your email list.
When the number of days set by you in the "screening period" (ie how many days they have to be subscribed to count as active) have passed, SparkLoop checks the status of the subscriber one last time. If they are still subscribed to your email list, it sends you a "new_partner_referral" webhook event to confirm the referral.
Until you receive a "new_partner_referral" webhook event from SparkLoop about a referral you should assume they are not confirmed as referral.
If the subscriber unsubscribes at any point, or if you want to disqualify them for any reason (eg: they haven't opened the emails you send them), you must send SparkLoop a "unsubscribe" event. In the absence of this event, SparkLoop will confirm the referral and count them towards your budget (unless they have been rejected for other reasons; ie anti-fraud).
Sending data TO SparkLoop
You must notify SparkLoop via webhooks when certain events happen:
when a new person signs up
when an existing subscriber unsubscribes or is "disqualified"
(optional) when an existing subscriber updates their email address
Incoming Webhook URL
You can find your incoming webhook URL by going to your Integrations page.
You should send all webhook events to this URL.
"subscribe" event
⚠️ 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 ID for this subscriber in your database, optional
"first_name": "John", // optional
"name": "John Doe", // optional
"created_at": 1564400550 // timestamp of the sign up, optional
}
}
"unsubscribe" event
When an existing subscriber unsubscribes, you should send SparkLoop a webhook notification with the following payload.
This event will immediately reject this subscriber, therefore you can also use it to disqualify any subscriber who doesn't meet your criteria (ie: open the first 3 emails you send them).
{
"type": "unsubscribe",
"subscriber": {
"email": "john.doe@email.com"
}
}
"update" event (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
}
}
Other Considerations
Make sure you send the payload with the right header:
Content-Type: application/json
If you're using a Webhooks Zapier integration, remember to setup this header on the custom request.
Receiving data FROM SparkLoop
SparkLoop will send you webhooks notifications in response to certain events:
when a new subscriber is synced with SparkLoop
when a referral is confirmed
Webhook URL
You can create a webhook to receive the events from SparkLoop by going to your Webhooks page.
Make sure to select the "New referrals from partners" and "Subscriber created or updated" events.
"sync_subscriber" event
This event is sent when a subscriber is added or updated in SparkLoop.
{
"type": "sync_subscriber",
"campaign_id": "MF6319db9890",
"subscriber": {
"id": "sub_hjdgc74u", // SparkLoop subscriber ID
"first_name": "John",
"name": "John Doe",
"source": "sparkloop-upscribe",
"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_partner_referral" event
When a referral is confirmed SparkLoop sends you this event, which includes data about the subscriber and the partner who referred them.
{
"type": "new_partner_referral",
"campaign": {
"id": "partner_campaign_de9c1c7c7bbc",
"referral_code": "1b5b5c4094",
"type": "partner_program",
"upscribe": true,
"partner_program_id": "partner_program_5b925f623c28"
"publication_id": "pub_a6db3f666c55",
"created_at": 1658780774
},
"subscriber": {
"id": "sub_042448acb02a",
"first_name": null,
"name": null,
"email": "test12345@test.com",
"source": "signup",
"referral_code": "6363a0b5",
"referred": true,
"tot_referrals": 0,
"referral_status": "verified",
"last_reward": null,
"partner_id": "partner_0a8a45c403f8",
"created_at": 1659536359
},
"partner": {
"id": "partner_0a8a45c403f8",
"name": "Jason Resnickss",
"logo": "http://dash.sparkloop.app/rails/active_storage/representations/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBPQT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--36ac8d234a450db1db32c62fe9e399b29a9e42f0/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaDdCam9VY21WemFYcGxYM1J2WDJ4cGJXbDBXd2RwQVpacEFaWT0iLCJleHAiOm51bGwsInB1ciI6InZhcmlhdGlvbiJ9fQ==--b97dd663f95aeeb4752185ef091f0728b0f28f4a/active_campaign.png"
}
}
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.