Omnisend API + MCP (2026): 2026-03-15 REST, official MCP v2

Omnisend runs a date-versioned REST API at https://api.omnisend.com/api, and the version to build against in 2026 is 2026-03-15-not v3 or v5, both still visible in the docs version picker and both superseded. There are no maintained first-party language SDKs: the only Omnisend-branded PHP client on GitHub was archived in 2021. Where Omnisend is ahead of its peer group is MCP, an official hosted Model Context Protocol server at https://mcp.omnisend.com/v2/mcp, already in its second generation.

One structural fact frames everything below: Omnisend has no SMTP relay and no transactional send endpoint. You push contacts, products and commerce events in, and an automation workflow decides what gets sent. That makes POST /api/events the most important endpoint on the platform, and it changes how you architect anything that would be a one-line SMTP submit on Brevo or Mailchimp.

At a glance

MCP integration in 2026

Model Context Protocol is how an AI client. Claude, ChatGPT, Cursor, discovers and calls a vendor’s API without custom glue code. For most email platforms in 2026 the answer is still a community wrapper on GitHub. Omnisend shipped first-party MCP, twice.

Available MCP servers

Two are Omnisend’s own. Note that aggregator directories, mcp.so, Glama, MCPlane, mcpbundles, UBOS, almost all index the community repo rather than the official hosted endpoint, and several mislabel it as official.

Omnisend API essentials

A conventional JSON REST surface with one unconventional rule: two headers are mandatory on every request, and omitting the version header silently puts you on a version you did not choose. Errors follow RFC 9457 problem+json.

The resource model is contact-and-event centric, not message centric. Fourteen groups cover Events, Contacts, Brands, Products, Categories, Batches, Campaigns, Segments, Email Content, Templates, Universal Layouts, Images and Analytics, plus Automations, roughly 130+ endpoints. Notably absent: anything that sends a specific message to a specific address on demand. Campaign statistics also moved into Analytics in 2026-03-15, which matters because those are the most throttled endpoints in the API.

Cursor pagination has one rule that trips people on day one: filters and sort are encoded inside the cursor, so once you have one you pass only the cursor. Changing a filter mid-pagination returns 400. Never send after and before together.

Authentication methods

Two paths, depending on whether you are integrating your own store or shipping an app other merchants install.

API key header

Generate a key in the Omnisend app and send it as Authorization: Omnisend-API-Key YOUR-API-KEY alongside the mandatory Omnisend-Version: 2026-03-15 header. This replaced the v3 X-API-KEY pattern outright: the old header is rejected on the new base path, and the old base path is retired. Porting pre-2026 code means changing both.

OAuth 2.0 for partner apps

Public and partner apps use the authorization code flow: send the user to https://app.omnisend.com/oauth2/authorize with client_id, redirect_uri, response_type=code, state and a space-separated scope; exchange at https://app.omnisend.com/oauth2/token; then call with Authorization: Bearer {access-token}. Tokens do not expire unless revoked, so there is no refresh loop, and no rotation either, so treat them as long-lived secrets. Connecting a brand via POST /api/brands/current is OAuth-only.

Scopes are declared per endpoint rather than published as one list. Confirmed strings include contacts.write, products.write and events.write; check the reference page for your endpoint before requesting a scope set.

Rate limits

Limits are enforced per brand on a sliding window over the last minute, or over 24 hours where a daily quota applies. The headline number is generous; the exceptions are what break integrations.

Exceeding a limit returns HTTP 429 with an RFC 9457 body: {"type":"https://problems.omnisend.com/rate-limit-exceeded","title":"Rate limit exceeded","status":429}. Some endpoints add retryAfter in seconds, read it rather than guessing. The analytics workaround is architectural: 55 calls per day is one refresh every 26 minutes for a single report, so a dashboard fanning out one call per widget exhausts its budget before lunch. Consolidate metrics into as few report calls as possible and cache server-side for at least 30 minutes. For contact and product sync, use the Batch API rather than looping single writes.

Official SDKs

The weakest part of the developer story: no maintained first-party client library exists for any general-purpose language. Omnisend ships a WordPress plugin family, a Postman workspace and machine-readable docs; everything else in the omnisend GitHub org is archived or not what its name suggests.

The maintained code is the WordPress family: wp-omnisend (last commit June 2, 2026) plus official bridges for SureCart, Gravity Forms, Contact Form 7, Ninja Forms, Formidable Forms, Paid Memberships Pro and LifterLMS. On WordPress that is your path; elsewhere, plan on a thin HTTP client.

Notable community SDKs

No widely adopted community client exists for Python, Node, Ruby or Go. The nearest thing is plutzilla/omnisend-mcp, whose source doubles as a reference implementation of the HTTP calls, plus Make‘s no-code module set. The honest 2026 recommendation: generate a client from the OpenAPI specs in llms.txt, or write 50 lines of fetch.

Endpoints reference

Fifteen of the most-used resources across the 130+ documented endpoints, relative to https://api.omnisend.com/api. The full reference is at api-docs.omnisend.com; every page has a Markdown twin reachable by appending .md, the fastest way to feed a spec to an agent.

Code examples

Python: upsert a contact, then trigger a message

There is no send call: you upsert the contact, emit an event, and a subscribed workflow composes and delivers the email. Money is a float in store currency, never integer cents. A 401 almost always means a legacy X-API-KEY header or a missing version header.

import requests

BASE = "https://api.omnisend.com/api"
HEADERS = {
    "Authorization": "Omnisend-API-Key YOUR-API-KEY",
    "Omnisend-Version": "2026-03-15",
    "Content-Type": "application/json",
}

# Upsert a contact: 201 create, 200 update
r = requests.post(f"{BASE}/contacts", headers=HEADERS, timeout=30, json={
    "identifiers": [{
        "type": "email",
        "id": "jane@example.com",
        "channels": {"email": {"status": "subscribed"}},
    }],
    "firstName": "Jane",
})
r.raise_for_status()
contact_id = r.json()["id"]   # renamed from contactID in 2026-03-15

# Trigger the send by emitting an event
ev = requests.post(f"{BASE}/events", headers=HEADERS, timeout=30, json={
    "contact": {"email": "jane@example.com"},
    "eventName": "placed order",
    "origin": "api",
    "properties": {"orderID": "1042", "value": 19.99, "currency": "USD"},
})
assert ev.status_code == 202, ev.text   # asynchronous; 19.99 NOT 1999

Node.js: cursor pagination with 429 backoff

const BASE = "https://api.omnisend.com/api";
const headers = {
  Authorization: `Omnisend-API-Key ${process.env.OMNISEND_API_KEY}`,
  "Omnisend-Version": "2026-03-15",
};

async function allContacts() {
  let params = new URLSearchParams({ limit: "250" });  // max 250
  const out = [];
  for (;;) {
    const r = await fetch(`${BASE}/contacts?${params}`, { headers });
    if (r.status === 429) {
      const problem = await r.json();   // RFC 9457 body
      await new Promise((s) => setTimeout(s, (problem.retryAfter ?? 60) * 1000));
      continue;
    }
    if (!r.ok) throw new Error(await r.text());
    const body = await r.json();
    out.push(...(body.contacts ?? []));
    const after = body.paging?.cursors?.after;
    if (!body.paging?.hasMore || !after) return out;
    params = new URLSearchParams({ after });   // cursor only
  }
}

Connecting the official MCP server

No API key is involved, the client opens a browser OAuth flow on first use. Claude: Customize › Connectors › Add custom connector. ChatGPT: Settings › Apps › Developer mode. Cursor takes the raw config.

{
  "mcpServers": {
    "omnisend": { "url": "https://mcp.omnisend.com/v2/mcp" }
  }
}

Common gotchas

Deprecations and changelog

• February 19, 2026-Branded click tracking shipped: campaign links render under the merchant’s own link domain, not Omnisend’s shared one.
• March 15, 2026-Version 2026-03-15 became current, superseding v3, v4.0 and v5. Breaking: new base path, new auth header, mandatory version header, RFC 9457 errors, cursor pagination, carts and orders removed as readable resources, money moved from integer cents to floats.
• May 4, 2026-SMS pricing cut to $0.007 per message on the latest Pro plan; SMS Sender ID registration became a per-country compliance requirement (Finland May 4, Spain June 7, Australia July 1).
• May 12, 2026-The Omnisend app landed in ChatGPT for plain-language questions about campaigns and subscribers, the first public step of the MCP rollout; on July 10 it gained creation of on-brand, editable emails inside the builder.
• July 30, 2026-Omnisend shipped as a Claude connector exposing the hosted MCP server at https://mcp.omnisend.com/v2/mcp. On July 14, “AI Apps Access” had added read-only, scoped and full-access tiers for AI connections.

Legacy v3, v4.0 and v5 remain in the docs version picker, and v2026-preview covers early-access Statistics and Forms endpoints. Omnisend publishes migration guides from v5 and v3, including an AI-agent-assisted path, but no end-of-life dates. Track the official changelog and API reference.

Frequently asked questions