Skip to main content
The public API lets your own systems work with an InstantCampaign workspace. You can upsert contacts and manage list membership, record events and goals, send transactional email, subscribe to webhooks, start journeys and connect AI agents over MCP. The pages in this tab are overviews. The full reference, with every request field, response schema and error code, is available to registered workspaces: open Settings → API reference in the app, or fetch the OpenAPI 3.1 document from GET https://instantcampaign.ai/api/v1/openapi.json while signed in or with a workspace API key. You can import that document into Postman, Insomnia or an OpenAPI code generator.
Only the endpoints documented here are public. The dashboard calls other /api/* routes with a browser session. Those routes are internal, they can change without notice, and they do not accept API keys.

​
Base URL

​
API keys

To create a key, open Settings → API Keys. Creating or deleting keys needs the API keys: manage permission: Owners, Administrators, or a custom role that grants it. The full key is shown once, when it is created. It starts with ic_. We keep only a hash of it, so a lost key has to be replaced. Send the key as a bearer token:
A key can have an expiry date. After that date every call with it answers 401. You can delete a key at any time on the same page.

​
Scopes

A key can be limited to scopes. A key with no scopes has full access. A key with scopes can only call endpoints whose scope it holds. Any other call answers:
Some routes (transactional, public events, MCP) leave out requiredScope, so check code. The journey trigger endpoint accepts a key with any scopes.

​
Rate limits

Limits are counted per workspace, per endpoint, per minute, and each endpoint has its own counter. Going over a limit answers 429 with { "error": "…" }. No Retry-After header is sent, so wait and retry with backoff.

​
Request size limits

Bodies are capped before they are read. A larger body answers 413 with code: "PAYLOAD_TOO_LARGE", and nothing is processed.

​
Errors

Errors are JSON with an error message. Many also include a machine-readable code.
A validation failure answers 400. Some routes also list the fields that failed:

​
Pagination

Two styles are used:
  • Page numbers. GET /v1/contacts takes page (from 1) and limit (1–100, default 50). It returns pagination: { page, limit, total, totalPages }.
  • Cursor. GET /v1/transactional takes limit (1–100, default 50) and returns nextBefore. To get the next page, pass that value back as before. nextBefore is null once a page comes back less than full.
GET /v1/lists returns every list in one response.

​
Idempotency

Two write endpoints take an externalId: a key of your own, unique per workspace. It is best to use the ID of the thing that caused the call, such as an order ID.
  • POST /v1/events, /v1/events/import and /public/events: a repeat answers 200 with status: "duplicate" and the original event’s ID, and records nothing.
  • POST /v1/transactional/send: a repeat answers 200 with the original message and deduplicated: true. Nothing is sent, even when the calls run at the same time.
POST /v1/webhooks/subscribe is naturally idempotent: subscribing the same event and URL again returns the existing subscription. No other endpoint deduplicates.

​
Request log

API calls are recorded in the request log under Settings → API log. That covers every call to /v1/*, /public/events, /public/journeys/trigger and /mcp. Viewing the log requires the API-keys management permission. Each row shows the time, method, path, status, duration, and the key that was used. It also shows whatever the call produced, such as a transactional message, event, journey run or contact, along with the recipient and externalId. Request and response bodies are stored for debugging, with a size cap. Fields whose names look like secrets (password, secret, token, authorization, apiKey, credential) are redacted, and attachment contents are left out. Rows are kept for 90 days. Calls that fail authentication are not logged, because there is no workspace to attach them to.

​
Webhooks

InstantCampaign can POST workspace events to your endpoints. For signing, retries and the difference between dashboard-registered endpoints and REST-hook subscriptions, see Webhooks.