EmailOctopus API + MCP (2026): v2 REST, no official MCP server

EmailOctopus exposes one programmatic surface: a REST API whose current generation is v2, launched October 7, 2024 at https://api.emailoctopus.com with Bearer auth, cursor pagination and RFC 7807 errors. It is a list-and-contact API, not a sending API — no message endpoint, no attachment upload, no SMTP relay — so anything transactional has to leave through a second provider. The agent verdict is equally blunt: no official MCP server in 2026, and every EmailOctopus MCP endpoint you can connect to is a third-party wrapper over that same v2 API.

At a glance

MCP integration in 2026

The Model Context Protocol gives an LLM client typed, permissioned access to a SaaS product instead of a scraped dashboard. For an ESP the question is simple: can an agent read your audience, tag contacts and trigger a flow with no glue code? For EmailOctopus in 2026 the answer is yes — but only through someone else’s infrastructure.

Available MCP servers

Four hosted options expose EmailOctopus over MCP. All authenticate with your own API key or an account link, and all inherit the same ceiling: whatever that vendor’s app already supports.

EmailOctopus API essentials

Everything below applies to v2. v1.6 lived on a different host with a different auth mechanism, is documented as legacy and unmaintained, and its keys are not portable to v2.

The resource model is deliberately small: lists, the contacts inside them, the fields and tags on those contacts, read-only campaign reports, and an automation queue you can push a contact into. Campaigns are composed in the dashboard and cannot be created over the API. Internalise that before designing an integration: EmailOctopus is an audience system of record with reporting attached, and dispatch stays inside the product. Teams needing a programmatic send path pair it with Amazon SES or a turnkey relay, exactly as the knowledge base recommends.

Authentication methods

Bearer token (v2)

v2 accepts one credential type: an API key created in account settings and sent as Authorization: Bearer eo_xxxxx. Keys are account-scoped, not list-scoped and not permission-scoped, so a key that can read a list can also delete contacts from it. Rotate by generating a new key and revoking the old one; there is no OAuth flow and no scope selector.

curl -sS -H "Authorization: Bearer eo_xxxxxxxxxxxxxxxx" https://api.emailoctopus.com/lists

Legacy api_key parameter (v1.6)

v1.6 passed the credential as an api_key query-string or body parameter against https://emailoctopus.com/api/1.6/. It still answers for existing keys — there has been no forced migration — but it is unmaintained and it leaks the credential into access logs and proxy caches. Treat any code path still doing this as debt with a deadline you set yourself, because EmailOctopus has published no sunset date.

Rate limits

EmailOctopus documents a token-bucket limiter: generous for list maintenance, tight for bulk backfills. Read it as a burst allowance plus a refill rate, not a flat per-minute quota.

The workaround for large imports is batching, not parallelism. PUT /lists/{list_id}/contacts/batch upserts many contacts per request, turning a 50,000-contact backfill from a rate-limit fight into a few hundred calls. If you must iterate per contact, cap concurrency at 10 in-flight requests and back off on X-RateLimiting-Remaining before the bucket empties — a 429 is expensive because it blocks the connection for up to a full minute rather than rejecting one call. Note what is not in the table: no hourly send ceiling, no recipients-per-message cap, no maximum message size — sending is not an API operation at all.

SDKs and client libraries

EmailOctopus maintains no official SDKs in any language. Its knowledge base lists 6 community projects and states they are unofficial and untested by the team. The stated position is that the API “plays nicely with any REST client in your chosen language”; EmailOctopus offers developer discounts to people who open-source a library instead of shipping one, and no public EmailOctopus GitHub organisation exists.

Notable community SDKs

The two PHP packages from goran-popovic are the most actively maintained and the only ones with a first-class Laravel path. The Ruby gem is the oldest and best read as reference code. On Node and Python, skip the wrapper: two fetch or requests calls cover contact upsert and pagination, which is most of what the API does.

Endpoints reference

The full v2 surface reads in one sitting. The fifteen entries below cover every documented resource plus the two behaviours common to all of them. Canonical reference: emailoctopus.com/api-documentation/v2.

Code examples

Authentication check with cURL

The cheapest way to confirm a key is a v2 key and not a stale v1.6 one: hit the lists collection and read the status line before debugging anything else.

curl -i -H "Authorization: Bearer eo_xxxxxxxxxxxxxxxx" "https://api.emailoctopus.com/lists?limit=1"

# 200 OK  -> key is valid for v2
# 401/403 -> key is a legacy v1.6 key, regenerate it in Account settings
#
# Useful response header:
#   X-RateLimiting-Remaining: 99

Python: upsert a contact and page the list

import hashlib
import requests

API_KEY = "eo_xxxxxxxxxxxxxxxx"   # v2 key from EmailOctopus > Account settings > API
BASE = "https://api.emailoctopus.com"
LIST_ID = "00000000-0000-0000-0000-000000000000"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. Upsert a contact (PUT on the collection = create or update by email)
resp = requests.put(
    f"{BASE}/lists/{LIST_ID}/contacts",
    headers=HEADERS,
    json={
        "email_address": "ada@example.com",
        "fields": {"FirstName": "Ada"},
        "tags": {"vip": True},
        "status": "subscribed",
    },
    timeout=30,
)
resp.raise_for_status()
contact = resp.json()

# contact_id is the MD5 of the LOWERCASED email address
print(contact["id"] == hashlib.md5(b"ada@example.com").hexdigest())

# 2. Page through every contact using the cursor in `paging.next`
url = f"{BASE}/lists/{LIST_ID}/contacts?limit=100"
while url:
    page = requests.get(url, headers=HEADERS, timeout=30).json()
    for c in page["data"]:
        print(c["email_address"], c["status"])
    url = (page.get("paging") or {}).get("next", {}).get("url")

# NOTE: no send/message endpoint exists - campaigns are sent from the dashboard.

Node.js: upsert, trigger an automation, handle 429

// npm i node-fetch@3   (or use global fetch on Node 18+)
const API_KEY = process.env.EMAILOCTOPUS_API_KEY; // v2 key
const BASE = 'https://api.emailoctopus.com';
const LIST_ID = '00000000-0000-0000-0000-000000000000';

const headers = {
  Authorization: `Bearer ${API_KEY}`,
  'Content-Type': 'application/json',
};

// 1. Upsert a contact
const res = await fetch(`${BASE}/lists/${LIST_ID}/contacts`, {
  method: 'PUT',
  headers,
  body: JSON.stringify({
    email_address: 'ada@example.com',
    fields: { FirstName: 'Ada' },
    tags: { vip: true },
    status: 'subscribed',
  }),
});
if (!res.ok) throw new Error(`EmailOctopus ${res.status}: ${await res.text()}`);

// 2. Trigger an automation for that contact
await fetch(`${BASE}/automations/AUTOMATION_ID/queue`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ contacts: [{ email_address: 'ada@example.com' }] }),
});

// 3. Cursor pagination, with 429 back-off
let url = `${BASE}/lists/${LIST_ID}/contacts?limit=100`;
while (url) {
  const r = await fetch(url, { headers });
  if (r.status === 429) { await new Promise(s => setTimeout(s, 60000)); continue; }
  const page = await r.json();
  url = page.paging?.next?.url ?? null;
}

Common gotchas

Deprecations and changelog

• July 22, 2026 — COO Tom Evans publishes an open letter, “why our free plan isn’t going anywhere”, committing to keep the free Starter tier.
• October 10, 2025 — Automation templates released. Relevant to API users because POST /automations/{automation_id}/queue is the only programmatic trigger.
• July 3, 2025 — “Contacts” replaces the Lists screen as the primary audience view. API resource names stay /lists.
• March 31, 2025 — Date-field automation triggers released; flows can start from custom date fields such as birthdays.
• October 7, 2024 — API v2 launched at api.emailoctopus.com with Bearer auth, cursor pagination and RFC 7807 errors. v1 keeps working but is documented as legacy; keys must be regenerated.
• August 30, 2019 — EmailOctopus drops the Amazon SES requirement for new signups, moving to its own partnered infrastructure. Connect stays available for teams that prefer their own SES account — the split still causing SMTP confusion in 2026.

Product updates: emailoctopus.com/blog/category/product-updates. API changes are announced in the v2 documentation.

Frequently asked questions