Data feeds from your API - InstantCampaign

A data feed pulls JSON from your own API while a campaign is being sent. You can use it for prices and stock levels that change daily, or for per-customer recommendations and loyalty balances. The template reads the data with Liquid. This page covers what your endpoint receives and must return. For turning feeds on in the send wizard, see Send a campaign.

Two kinds of feed

Feed	Fetched	In the template
Global data feed	Once per send, before the first email	`{{ global_feed.… }}`
Per-recipient data feed	For each recipient, just before their email is rendered	`{{ recipient_feed.… }}`

Both are set on the Data feeds step of the send wizard, with a URL, a method (GET or POST) and optional headers, one per line (Authorization: Bearer abc123). Headers are stored encrypted. The per-recipient URL can use Liquid with the contact’s fields, for example:

https://api.example.com/customers/{{ contact.email | url_encode }}/recommendations

With POST, the per-recipient request also carries this body:

{ "contact": { "id": "clx…", "email": "ana@example.com", "externalId": "cus_123" } }

In the template, use the data like any Liquid value:

<h2>{{ global_feed.deal.title }}, today only</h2>
{% for item in recipient_feed.recommendations limit:3 %}
  <p>{{ item.name }}: {{ item.price }}</p>
{% endfor %}

What your endpoint must do

Be reachable on the public internet. Private and internal addresses are refused.
Answer with JSON of 256 KB or less.
Answer within 5 seconds. A 5xx answer, a timeout or a network error is retried once.

Before you can continue past the Data feeds step, you have to click Preview with a sample contact and get a successful result. The preview fetches both feeds for a sample contact and renders the subject, so mistakes show up before anything is sent.

Verify requests

Every feed request carries two headers:

X-IC-Timestamp: when the request was made, in milliseconds since the Unix epoch
X-IC-Signature: a hex HMAC-SHA256 of <timestamp>.<url>, signed with your workspace’s signing key. <url> is the exact URL requested, with the per-recipient Liquid already filled in.

The signing key is shown in the preview result as Signing key (verify X-IC-Signature). Keep it secret on your server.

import crypto from "node:crypto";

export function isFromInstantCampaign(req, signingKey) {
  const timestamp = req.headers["x-ic-timestamp"];
  const signature = req.headers["x-ic-signature"];
  if (!timestamp || !signature) return false;

  // Reject old requests (5 minutes).
  if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) return false;

  const url = `https://${req.headers.host}${req.originalUrl}`; // the full URL that was requested
  const expected = crypto
    .createHmac("sha256", signingKey)
    .update(`${timestamp}.${url}`)
    .digest("hex");

  return (
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))
  );
}

Rebuild the URL exactly as InstantCampaign requested it, including the scheme, host, path and query string. A proxy that rewrites the host or path makes the signature fail to match.

When a feed fails

Global feed: the whole send fails, and the reason is shown on the campaign.
Per-recipient feed: you choose what happens under If the feed fails:
- Skip the recipient (shown in the message log): the default. The recipient gets no email, and the message log records why.
- Send with an empty recipient_feed: the email goes out, and recipient_feed is empty. Write the template so it still reads well, for example with {% if recipient_feed.recommendations %}.

Limits per send

Per-recipient fetches are capped per plan. Recipients beyond the cap are handled as a failed feed, following your If the feed fails choice.

Plan	Per-recipient fetches per send
Free	500
Essential	2,500
Pro	20,000
Enterprise	Unlimited

Other things to know:

Per-recipient requests run eight at a time, so allow for that load on your API.
Each recipient’s result is stored. If a send is interrupted and resumed, your API isn’t called again for recipients already fetched.
A/B test variants and the winning version use the same feeds.
Data feeds work in campaigns (broadcasts). They don’t apply to journey emails.

​Two kinds of feed

​What your endpoint must do

​Verify requests

​When a feed fails

​Limits per send

Two kinds of feed

What your endpoint must do

Verify requests

When a feed fails

Limits per send