A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Omnisend API is how an app or AI agent works with an Omnisend store: adding or updating a contact, sending an event like a started checkout to trigger an automation, syncing products and categories, recording carts and orders, and listing email, SMS and push campaigns. Access is granted through a store API key, which is created at the account level and reaches everything that key's account can, with a newer OAuth option that narrows access to per-resource scopes. Omnisend is built to receive events that set off its automations, rather than to push events back out.
How an app or AI agent connects to Omnisend determines what it can reach. There is a route for calling the REST API directly, and a hosted server that exposes Omnisend operations to AI agents, and each is governed by the key or grant behind it.
The stable v3 REST API takes JSON request bodies, returns JSON, and pages lists through offset and limit, at https://api.omnisend.com/v3. A call authenticates with a store API key in an X-API-KEY header. This is the line where carts and orders are managed as full resources.
The newer REST line pins a dated version through an Omnisend-Version header, like 2026-03-15, and pages through opaque before and after cursors, at https://api.omnisend.com/api. It accepts a store key as an Authorization: Omnisend-API-Key header or an OAuth 2.0 Bearer token carrying per-resource scopes such as contacts.read and events.write.
A first-party hosted Model Context Protocol server at https://mcp.omnisend.com/mcp exposes Omnisend operations to AI agents through a small set of generic tools (search, tool_schema, tool_documentation, and execute) that reach the wider API. It authenticates through Omnisend's OAuth flow, and the user approving it needs an Owner, Admin, Manager or Partner role. A newer action-specific server is offered at https://mcp.omnisend.com/v2/mcp.
An API key is generated in the Omnisend account and represents the whole account: it has no granular per-endpoint scopes, so it can read and write every resource the account can reach. v3 sends it in an X-API-KEY header; the newer line sends it as an Authorization: Omnisend-API-Key header. The key is shown only once when created and cannot be viewed again.
The newer line supports the OAuth 2.0 authorization-code flow, authorizing at app.omnisend.com/oauth2/authorize and exchanging the code at app.omnisend.com/oauth2/token. The requested scope is a space-separated list of per-resource permissions, like contacts.read and events.write, and the resulting access token is sent as a Bearer token. This is the only way to narrow what a single grant can do.
The Omnisend API is split into areas an agent can act on, like contacts and their subscription consent, store data such as products, categories, carts and orders, the events that trigger automations, and the campaigns that send email, SMS and push. A write in some areas changes who is contacted or what a customer receives.
Methods for listing, reading, creating and updating contacts and their subscription consent.
Methods for sending the events that trigger Omnisend automations.
Methods for syncing the store product catalogue.
Methods for managing product categories.
Methods for recording carts that drive abandoned-cart automations.
Methods for recording orders created through the API for order automations.
Methods for listing and reading email, SMS and push campaigns.
Methods for running many create or update actions in one bulk request.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ContactsMethods for listing, reading, creating and updating contacts and their subscription consent.4 | ||||||
| GET | /v3/contacts | List contacts, optionally filtered by status, segment, tag or email. | read | — | Current | |
v3 store key has no per-endpoint scope; on the newer line the OAuth scope is contacts.read. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/contacts/{contactID} | Retrieve a single contact by its Omnisend contact id. | read | — | Current | |
v3 store key has no per-endpoint scope; on the newer line the OAuth scope is contacts.read. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/contacts | Create a contact, or update the existing one matching the email or phone. | write | — | Current | |
Sets subscription status per channel; the newer line OAuth scope is contacts.write. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/contacts/{contactID} | Update a contact's properties, tags or subscription status by id. | write | — | Current | |
Can change consent, so it affects who is messaged; newer line OAuth scope is contacts.write. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsMethods for sending the events that trigger Omnisend automations.1 | ||||||
| POST | /v3/events | Send a recommended or custom event for a contact to trigger an automation. | write | — | Current | |
Can start an automation that sends messages; the newer line path is /api/events with OAuth scope events.write. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProductsMethods for syncing the store product catalogue.5 | ||||||
| GET | /v3/products | List products in the synced store catalogue. | read | — | Current | |
Newer line path is /api/products with OAuth scope products.read. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/products/{productID} | Retrieve a single product by its id. | read | — | Current | |
Newer line OAuth scope is products.read. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/products | Create a product in the catalogue. | write | — | Current | |
Newer line OAuth scope is products.write. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/products/{productID} | Replace a product, overwriting its stored data with the request body. | write | — | Current | |
A full replace; the newer line uses PUT /api/products/{productId} with OAuth scope products.write. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/products/{productID} | Delete a product from the catalogue. | write | — | Current | |
Irreversible; the newer line OAuth scope is products.write. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Product categoriesMethods for managing product categories.3 | ||||||
| GET | /v3/categories | List product categories. | read | — | Current | |
Newer line path is /api/product-categories with OAuth scope products.read. Acts oncategory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/categories | Create a product category. | write | — | Current | |
Newer line path is /api/product-categories with OAuth scope products.write. Acts oncategory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/categories/{categoryID} | Replace a product category, overwriting its stored data. | write | — | Current | |
On the newer line this is PATCH /api/product-categories/{categoryId} with OAuth scope products.write. Acts oncategory Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CartsMethods for recording carts that drive abandoned-cart automations.8 | ||||||
| GET | /v3/carts | List carts recorded through the API. | read | — | Current | |
v3 store key has no per-endpoint scope. Acts oncart Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/carts/{cartID} | Retrieve a single cart by its id. | read | — | Current | |
v3 store key has no per-endpoint scope. Acts oncart Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/carts | Create a cart; an email or contactID must be provided so it can drive an abandoned-cart automation. | write | — | Current | |
Can start an abandoned-cart workflow; v3 store key has no per-endpoint scope. Acts oncart Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/carts/{cartID} | Update a cart's details by id. | write | — | Current | |
v3 store key has no per-endpoint scope. Acts oncart Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/carts/{cartID} | Delete a cart by id. | write | — | Current | |
Irreversible; v3 store key has no per-endpoint scope. Acts oncart Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/carts/{cartID}/products | Add a product to a cart. | write | — | Current | |
v3 store key has no per-endpoint scope. Acts oncart_product Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/carts/{cartID}/products/{cartProductID} | Update a product in a cart, such as its quantity or price. | write | — | Current | |
v3 store key has no per-endpoint scope. Acts oncart_product Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/carts/{cartID}/products/{cartProductID} | Remove a product from a cart. | write | — | Current | |
v3 store key has no per-endpoint scope. Acts oncart_product Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrdersMethods for recording orders created through the API for order automations.5 | ||||||
| GET | /v3/orders | List orders created through the API. | read | — | Current | |
Only orders created via the API; platform-synced orders are not exposed here. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/orders/{orderID} | Retrieve a single order by its id. | read | — | Current | |
v3 store key has no per-endpoint scope. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/orders | Create an order; an email, phone or contactID must be provided to drive order automations. | write | — | Current | |
Can trigger order confirmation messages; v3 store key has no per-endpoint scope. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v3/orders/{orderID} | Replace an order, overwriting all stored order data with the request body. | write | — | Current | |
A full overwrite; v3 store key has no per-endpoint scope. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v3/orders/{orderID} | Update an order's status, such as fulfilled, canceled or refunded. | write | — | Current | |
A status change can trigger a follow-up automation; v3 store key has no per-endpoint scope. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CampaignsMethods for listing and reading email, SMS and push campaigns.2 | ||||||
| GET | /api/campaigns | List email, SMS and push campaigns, filterable by status, channel and type. | read | — | Current | |
On the newer, version-pinned line; OAuth scope is campaigns.read. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/campaigns/{id} | Retrieve a single campaign by its id. | read | — | Current | |
On the newer, version-pinned line; OAuth scope is campaigns.read. Acts oncampaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BatchesMethods for running many create or update actions in one bulk request.2 | ||||||
| POST | /v3/batches | Run up to 100 create or update actions of one type in a single bulk request. | write | — | Current | |
Up to 100 actions per batch across contacts, products, events or categories; newer line path is /api/batches. Acts onbatch Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/batches/{batchID} | Get the status and results of a batch by its id. | read | — | Current | |
Newer line path is /api/batches/{batchId}. Acts onbatch Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Omnisend is built to take in events, not to push them out. An app or AI agent sends an event like a started checkout or a placed order, and Omnisend matches it to an automation that sends the message, so there is no outbound event feed to subscribe to here.
| Event | What it signals | Triggered by |
|---|
Omnisend limits how fast an app can call, by a request rate measured per minute on a single store key, and it reports the remaining allowance on every response.
Omnisend meters requests by a per-minute rate on the store key rather than by a per-method cost. The v3 API allows 400 requests per minute across the account; the newer line sets lower per-operation ceilings, with list reads commonly at 100 per minute, writes at 15 per minute, and analytics reports at 10 per minute and 55 per day. Going over returns HTTP 429, and some responses include a retryAfter value in seconds. The v3 API reports the current allowance on every response through X-Rate-Limit-Limit, X-Rate-Limit-Remaining and X-Rate-Limit-Reset headers.
The v3 API pages through a list with offset and limit query parameters. The newer line uses cursor pagination: a response carries paging.cursors with opaque before and after values and a hasMore flag, and a limit of up to 250 items per page (default 100). Lists can also be sorted, for example by createdAt or updatedAt, ascending or descending.
A page returns at most the configured limit, capped at 250 on the newer line. A batch request, which groups many create or update actions into one call, accepts up to 100 actions per batch.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | validation_error | The request body was invalid: a required field is missing or wrongly formatted. The v3 response carries an error description, a statusCode, and a fields array naming each problem; the newer line returns an RFC 9457 problem object with title, detail and an errors array. | Read the fields or errors array, correct each named field, and resend. The request is not retryable as-is. All validation problems are reported at once. |
| 401 | unauthorized | No valid credential was provided: a missing, wrong, or revoked API key or OAuth token. | Confirm the X-API-KEY, Omnisend-API-Key, or Bearer token is correct and still active, and rotate it if it may be compromised. |
| 403 | forbidden | The credential is valid but lacks permission for this request, for example an OAuth token without the resource scope the call needs. | Request the missing scope in the OAuth grant, or use a credential with access to the resource. |
| 404 | not_found | The requested object does not exist or is not visible to this account, for example an unknown contact, cart or order id. | Verify the id and confirm it belongs to the same store account. |
| 429 | rate-limit-exceeded | Too many requests arrived too quickly for the per-minute limit on the store key. The body may include a retryAfter value in seconds. | Back off and retry after the reset. On v3, read X-Rate-Limit-Remaining and X-Rate-Limit-Reset to pace requests; on the newer line, honour retryAfter. |
| 500 | server_error | An error on Omnisend's side. It is rare. | Retry with backoff, and include the instance trace id from the response when contacting support. |
Omnisend runs two generations of its API side by side: a stable v3 that uses a store API key, and a newer line that pins a dated version through a request header and adds OAuth with per-resource scopes.
The newer generation of the Omnisend API pins a dated version through the Omnisend-Version header (for example 2026-03-15), so behaviour stays stable for an existing integration while new capabilities ship under newer dates. It adds OAuth 2.0 with per-resource scopes alongside the store key, cursor pagination, and an RFC 9457 problem-detail error model. Contacts, events, products, categories, campaigns, segments, templates and batches are documented here.
The long-standing v3 API authenticates with a store API key in an X-API-KEY header at https://api.omnisend.com/v3, pages lists through offset and limit, and is metered at 400 requests per minute with X-Rate-Limit-* headers on every response. Carts and orders are managed as full resources here. Its error responses carry an error string, a statusCode, and a fields array for validation problems.
Build on the version that matches the key and scopes an integration needs.
Omnisend API changelog ↗Bollard AI sits between a team's AI agents and Omnisend. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.