What we do
Tools
Industries
Department
How we workLet's talk →
Home/Iterable
Iterable developer reference

The Iterable API: Keys, Endpoints and the Rules That Break Syncs

Iterable's REST API is how your app, billing system or warehouse tells Iterable who a user is and what they just did, so journeys and campaigns can react. The calls are simple JSON posts. What catches people out is which key to use where, which endpoint to send to, and a handful of rules about field types and timing that fail quietly. All of that is below.

Where Iterable stops

It can send across email, push, SMS and in-app, but is it sending on data that's actually current?

Stuck on Iterable? Let's solve it →
Before the first call

Base URL: https://api.iterable.com/api/. Projects hosted in Iterable's EU data center use https://api.eu.iterable.com/api/ instead, and a key from one won't work on the other.

Auth: send the key in an Api-Key header on every request. JWT-enabled keys also need a signed JWT in an Authorization: Bearer header.

Integrations API Keys

Key type: a server-side key reaches almost every endpoint and belongs only on your servers. A client-side key is the one for web and mobile SDK code, and only reaches a limited set of endpoints.

Which Iterable endpoint for which job

Rate limits are the ones Iterable publishes in its API reference, per project unless noted.

What you need to do Endpoint Know before you build
Create or change one user profile POST /api/users/update (500 requests a second) Fields you send are merged in. Fields you leave out stay as they were, so this is safe for partial updates.
Load or refresh many profiles at once POST /api/users/bulkUpdate (5 requests a second) Top-level fields you send overwrite what's there. Set mergeNestedObjects to true if nested objects should be merged rather than replaced.
Record something a user did POST /api/events/track (2,000 a second) or /api/events/trackBulk (10 a second) Bulk and single events are processed separately. Pick one endpoint per event stream or the order isn't guaranteed.
Purchases and abandoned carts POST /api/commerce/trackPurchase and /api/commerce/updateCart A tracked purchase clears the user's shoppingCartItems, which is what ends an abandoned-cart journey for them.
Product or content data for personalisation POST /api/catalogs/{catalogName}/items (100 a second, per key) Up to 1,000 items per request. An item with an existing ID is overwritten in full unless you set replaceUploadedFieldsOnly.
Start a journey or send one email from code POST /api/workflows/triggerWorkflow or /api/email/target Iterable advises leaving at least 60 seconds between updating a user and a send that depends on that update.
Pull campaign results out GET /api/export/data.csv (4 requests a minute) Slow by design. For anything near real time, have Iterable push events to you with a webhook instead.

Why Iterable data looks wrong after an integration goes live

None of these throw an error you'd notice in a dashboard. They show up as a send that used old data.

A field changed type

How you'll know: plan_renewal was first sent as a string, now your code sends a date, and the profile stops updating.

Fix: Field types are fixed by the first value Iterable sees across the project. Agree the type of every field before launch, and send a new field name rather than reusing an old one with a new type.

The send beat the update

How you'll know: A user upgrades and the confirmation email still shows their old plan.

Fix: Profile updates are processed asynchronously. Put the plan in the event that triggers the email, or wait the buffer Iterable recommends before calling the send.

Events from two pipelines arrive out of order

How you'll know: A backfill job uses trackBulk, the live app uses track, and a journey sees the cancellation before the signup.

Fix: Send each event stream through one endpoint only. If you need both, keep them to different event names.

Duplicate users from mixed identifiers

How you'll know: The same person appears twice, once keyed by email and once by userId.

Fix: Decide which identifier your project uses before the first sync, and send it on every call, including from the mobile SDK.

A server-side key in the app

How you'll know: The key sits in a JavaScript bundle or a mobile build, where anyone can read it.

Fix: Rotate it now, and give the app a client-side key, ideally JWT-enabled so each request is tied to a signed-in user.

Field sprawl

How you'll know: Every team adds its own fields until the project nears Iterable's soft limit of 1,000 unique user fields.

Fix: Keep a short field dictionary and nest related values under one object rather than flattening everything to the top level.

Getting engagement back out of Iterable

Sends, opens and clicks are only useful to sales and support if they leave Iterable. Webhooks are the push route: Iterable posts events to your endpoint, with no auth, Basic auth or OAuth2, and each webhook can be switched on for blast campaigns, triggered campaigns or both. The export API covers backfills, at four requests a minute.

On the receiving end, n-frames writes that engagement onto the matching contact in your CRM or into your warehouse, for example onto Salesforce records through the Salesforce REST API. Teams comparing platforms can see how the same jobs look in Braze and the Klaviyo API, and transactional email events are covered under SendGrid webhooks.

Nightly import or event calls?

Most Iterable projects start on a scheduled file load. It's fine until a journey has to react to something that happened this morning.

Scheduled import

A file or warehouse sync once a day

  • Easy to set up and easy to rerun.
  • An upgrade, a cancellation or a refund reaches Iterable hours later.
  • Messages can contradict what the customer just did.
Event-driven

API calls from the system where the change happens

  • Billing or the app calls users/update or events/track the moment something changes.
  • Journeys start on the real event, with the data it needs in the payload.
  • Needs retries and a log, so a failed call is visible instead of lost.

Keep the nightly load as a safety net for slow-moving fields, and move anything a journey triggers on to event calls.

A mobile app company on a nightly Iterable load

Mobile app company · Iterable messaging fed by a nightly data load

Before

When a user upgraded or cancelled, Iterable only learned about it at the next scheduled load.

In between, messages went out that contradicted what the customer had just done in the app.

After

Plan tier and account changes now reach the user's Iterable profile from the backend as they happen.

Each message now matches what the customer just did.

Questions people ask

What is Iterable used for?

Running email, push, SMS and in-app messages from one place, with journeys that start on what a user actually does. The API is how those user profiles and events get in from your own systems.

Is Iterable a CRM?

No. It keeps profiles and behavior so it can message people. Deals, pipelines and support cases live in a CRM, and most companies sync engagement data from Iterable into that CRM so both sides see it.

Where do I log into Iterable?

At app.iterable.com for US-hosted projects. EU-hosted projects have their own EU address, which matches the EU API host. If you're unsure which project you belong to, the original invite email says.

How much does Iterable cost?

Iterable doesn't publish a price list. It quotes by contact volume and the channels and features you use. API access comes with the platform, so the build cost is the integration work rather than an extra license.

What are good alternatives to Iterable?

Braze is the closest like-for-like for app-heavy businesses, and Klaviyo is the common pick for ecommerce. All three take profiles and events over an API, so a clean integration can be pointed at a different platform later without starting over.

Does Iterable have AI features?

Yes. Iterable markets AI tools inside the platform, such as send-time optimisation and predictions based on past engagement. They learn from the events and profile data you send, which is another reason to get field types and event timing right first.

Can I use the Iterable API from a website or mobile app?

Yes, with a client-side key through Iterable's web or mobile SDKs, which only reach the endpoints an app needs. Anything that writes on behalf of many users, such as a billing sync, belongs on a server with a server-side key.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.