Skip to main content
All CollectionsPartner Programs
Custom Integration
Custom Integration
Manuel Frigerio avatar
Written by Manuel Frigerio
Updated over a week ago

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.

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

For custom integrations, there are a couple of setup requirements:
​

Establishing a method to transmit data to SparkLoop: You must send an API call 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. 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 (optional. Only required if you want to allow partners to send subscribers directly to your website)

  • send API calls to SparkLoop when certain events (like a new signup or an existing subscriber unsubscribes) 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

  1. There are several ways in which a subscriber can be sent to you: directly to your website (via a referral link), via Upscribe or via a Magic link.
    ​
    If a person signs up directly on your website, our script (installed on your website) tracks the sign-up automatically. You have to send SparkLoop an API call to confirm the subscriber.
    ​

  2. As soon as the subscriber is processed, SparkLoop runs a referral assignment process that includes checking for fraudulent referrals, the email's validity, etc.
    ​

    If the subscriber is immediately rejected (eg: they are fraudulent or are based in a country that doesn't match your geo requirements), SparkLoop sends you a "sync_subscriber" webhook event where the referral_status will be set to "rejected".
    ​

    Otherwise, SparkLoop sends you a "new_partner_pending_referral" webhook event.
    ​

  3. You add the subscriber to your email list.
    ​

  4. If at any point during the screening period the subscriber unsubscribes you must send SparkLoop a "unsubscribe" API call. Also, if you want to reject the subscriber at any point during the screening period, for example because they have not met your engagement criteria, you must send a "reject" API call.
    ​
    When you do that, SparkLoop will send you a "sync_subscriber" webhook event where the referral_status will be set to "rejected".
    ​
    ​Note: it is your responsibility to let SparkLoop know when a subscriber unsubscribes or has not met your engagement criteria. In the absence of these notifications, SparkLoop will confirm the referral and charge you for them.
    ​

  5. When the screening period is over, SparkLoop will do a final assessment of the subscriber.
    ​
    If everything went well (the subscriber has not been unsubscribed or rejected), SparkLoop will send you a "new_partner_referral" webhook event to confirm the referral.
    ​
    Otherwise it send you a "sync_subscriber" webhook event where the referral_status will be set to "rejected".
    ​

  6. Until you receive a "new_partner_referral" webhook event from SparkLoop you should assume a subscriber has not confirmed as a referral.

Sending data TO SparkLoop

You must notify SparkLoop when certain events happen:

  • when a new person signs up (optional)

  • when a referral unsubscribes

  • when a referral is rejected (because they didn't meet your engagement criteria)

  • when an existing subscriber updates their email address (optional)

Confirm new subscriber

Note: you should ONLY do this if you have enabled partner links, ie if you allow partners to send subscribers directly to your website (which requires installing the SparkLoop tracking script).

When a new person signs up on your website you should let SparkLoop know so we can correctly assign the referral.

To do this you need to send an API call to the update subscriber API endpoint and make sure to send a status of confirmed.

The tracking script you have installed on your website will have already tracked the signup. With this API call you're simply confirming the subscriber has actually been added to your list. If you use double opt-in, you must send this event AFTER they confirm their email address.

Failure to confirm subscribers will result in the referral not being tracked in SparkLoop.

Unsubscribe an existing referral

When a referral that's been sent you unsubscribes from your email list you should let SparkLoop know so we can reject the referral and not charge you.

To unsubscribe a referral you can use the unsubscribe API endpoint.

Reject an existing referral

When a referral that's been sent you doesn't meet your engagement criteria within your screening period (for example, they don't open the minimum number of emails) you should let SparkLoop know so we can reject the referral and not charge you.

To reject a referral you can use the reject API endpoint.

Note: According to SparkLoop's terms and conditions, rejected referrals can't be emailed from you and must be unsubscribed from your email list.

Update a referral's email address (optional)

When an existing subscriber changes their email address, you should notify SparkLoop.

To do this you need to send an API call to the update subscriber API endpoint and make sure to pass the new email address in the email parameter.

Receiving data FROM SparkLoop

SparkLoop will send you webhooks notifications in response to certain events:

  • when a new referral is rejected

  • when a referral's screening period starts

  • when a referral is confirmed

Setting up a webhook

You can create a webhook to receive the events from SparkLoop by going to your Webhooks page.

Make sure to select the "New pending referral from partner", "New confirmed referral from partner" and "Subscriber created or updated" events.

Webhooks retries

If our webhooks notifications fail to deliver, we will retry for up to a 21 days with exponential back-off.

Did this answer your question?