Benchmark Email API + MCP (2026): drafts yes, sending no

Benchmark Email ships a modern REST API-Benchmark Email API v1.0.0, launched April 2026 at developers.benchmarkemail.io, with scoped X-API-Key auth, an OpenAPI spec and per-account regional base URLs. What it does not ship is a way to send: campaigns can be created, configured and duplicated over the API, but scheduling, sending and test-sending are web-app only, and no SMTP relay or transactional endpoint exists at any plan tier.

On the agent side there is no official MCP server as of August 2026-only third-party access via Zapier or Composio. The ceiling here is structural, not a pricing gate.

At a glance

MCP integration in 2026

Model Context Protocol gives an AI assistant a typed tool interface instead of guessing at HTTP calls. For an ESP the real question is not whether an agent can read your lists, any wrapper does that, but whether it can close the loop and send. For Benchmark the answer is no, and no MCP server can change it.

Available MCP servers

Two production-usable options, both authenticating with your own key, so their traffic spends your budget.

Benchmark Email API essentials

The current API is documented at developers.benchmarkemail.io with an OpenAPI document at /openapi.json. The detail that trips up most first integrations: the base URL is not global. Each account is pinned to a region and cluster, so hardcoding the docs example ships a client that 401s everywhere else.

The resource model is narrow and marketing-shaped: contacts, contact structures (the container defining your custom-field schema), lists, campaigns, templates, domains, reports. Note the hierarchy, lists are not top-level, they live at /api/contact-structure/{id}/lists, so most list work starts by resolving a structure id. GET /api/contact-structure is therefore the smoke test for a new key: cheap, read-scope, and it confirms base URL and region at once.

Authentication methods

Three schemes are live at once because three APIs are. Only the first applies to anything you should build in 2026.

X-API-Key (current API v1.0.0)

Keys are created by the account owner only, at Settings › API Keys, and displayed exactly once, a lost key means issuing a new one. The format is bme_{2-letter region}_{43 random chars}, 50 characters; the embedded region is a handy check that you are calling the matching host. There is no OAuth flow and no bearer variant.

Keys carry per-resource scopes-contacts, campaigns, reports, domains, each :read or :write, with write implying read. Active keys are capped at 2 on Free and 10 on Pro.

AuthToken (legacy RESTful API v3.0)

The deprecated v3.0 API at clientapi.benchmarkemail.com uses an AuthToken header carrying an admin token from ui.benchmarkemail.com/Integrate#AP. It is unscoped and account-wide, still works, has no published sunset date, and outranks the current docs in search, which is why so many 2026 integrations get built against it by accident.

Token methods (legacy XML-RPC v1.0)

The oldest surface, at apidocs.benchmarkemail.com, uses XML-RPC with token-based security methods. Every SDK in the BenchmarkEmail GitHub org targets it. Treat anything mentioning XML-RPC as archaeology, not a starting point.

Rate limits

Two independent ceilings stack, and both return the same status code, so the response alone will not tell you which wall you hit.

Breaching either limit returns HTTP 429 with errorType: TooManyRequestsError and a Retry-After header in seconds; the same 429 also signals IP-level blocks, which expire on their own. The workaround is budget-aware batching, not backoff tuning: retry only on 429, seeding backoff from Retry-After-a 401 or 403 is a config error that retrying just burns quota on. Drive contact sync through POST /api/contact/search at pageSize 50 so 50,000 contacts cost 1,000 calls, and check X-Monthly-Remaining before a full resync.

Official SDKs

The weakest part of the developer story: there is no official SDK for the current API. The five wrappers in the BenchmarkEmail GitHub org all describe themselves as XML-RPC clients for the legacy v1.0 API and predate the 2026 rewrite by years. They are listed so you can avoid them.

Notable community SDKs

There is no real community ecosystem either, unsurprising for an API four months old with no send capability to build on. The closest substitutes are workflow clients: the certified Power Automate connector and the community n8n node. Neither gives you typed models in your own codebase; for that, openapi-generator against /openapi.json emits a serviceable client in one command.

Endpoints reference

The full surface is in the official API reference; prefix every path with your base URL. Note what is absent: no /send, no /schedule, no /transactional, no webhooks.

Reporting sits at /api/reports/dashboard, /api/reports/email/{campaignId} and a sibling /engagement path. Duplication is the closest thing to a templating workflow: clone a known-good campaign, PATCH subject and lists, hand the draft over.

Code examples

Python, paginated contact sync and a budget probe

Never call GET /api/contact against a real database; page through POST /api/contact/search, retry only on 429, and read the budget headers before a full resync.

import os, requests

# NOT a global endpoint - read yours from Settings > API Keys.
BASE = os.environ["BENCHMARK_API_BASE_URL"].rstrip("/")
s = requests.Session()
s.headers.update({"X-API-Key": os.environ["BENCHMARK_API_KEY"],
                  "Content-Type": "application/json"})

def search(page=1, page_size=50):
    """GET /api/contact returns EVERY contact unpaginated. Use this."""
    r = s.post(f"{BASE}/api/contact/search",
               json={"page": page, "pageSize": page_size}, timeout=30)
    if r.status_code == 429:                     # retry ONLY on 429
        raise RuntimeError(f"retry in {r.headers.get('Retry-After', 60)}s")
    r.raise_for_status()
    return r.json()

def iter_contacts(page_size=50):
    first = search(1, page_size)
    yield from first["contacts"]
    pages = -(-first["totalRecords"] // page_size)   # ceil division
    for p in range(2, pages + 1):
        yield from search(p, page_size)["contacts"]

probe = s.get(f"{BASE}/api/contact-structure", timeout=30)
print("monthly budget left:", probe.headers["X-Monthly-Remaining"])

Node.js, both pagination conventions

One client covering contacts and campaigns, plus a draft. Note where the pipeline stops.

// Benchmark Email API v1.0.0 - Node 18+
const BASE = process.env.BENCHMARK_API_BASE_URL.replace(/\/$/, '');
const headers = { 'X-API-Key': process.env.BENCHMARK_API_KEY,
                  'Content-Type': 'application/json' };

async function call(path, options = {}) {
  const res = await fetch(`${BASE}${path}`, { ...options, headers });
  if (res.status === 429)              // retry ONLY on 429
    throw new Error(`retry in ${res.headers.get('Retry-After') ?? 60}s`);
  if (!res.ok) throw new Error(`${res.status}`);  // {errors:[{errorType}]}
  return res.json();
}

// Contacts: page/pageSize go in the BODY...
const searchContacts = (page = 1, pageSize = 50) =>
  call('/api/contact/search',
       { method: 'POST', body: JSON.stringify({ page, pageSize }) });

// ...campaigns use the QUERY STRING and rename pageSize to `size`.
const listCampaigns = (page = 1, size = 25) =>
  call(`/api/email/campaign?page=${page}&size=${size}`);

// Create a DRAFT. Only `name` is required. Pipeline stops here:
// no send, no schedule, no webhook.
const draft = await call('/api/email/campaign',
  { method: 'POST', body: JSON.stringify({ name: 'August Update' }) });

Common gotchas

Deprecations and changelog

• April 1, 2026-REST API v1.0.0 launched: scoped X-API-Key auth, OpenAPI spec, regional base URLs, key caps of 2 Free / 10 Pro. Supersedes RESTful API v3.0, with no sunset date published for it.
• April 1, 2026-Domain authentication gained DNS copy warnings, extended retry timing and clearer record viewing; send failures now give a specific reason instead of a generic “Failed”.
• April 1, 2026-Annual billing introduced at roughly 15% saving versus monthly; user billing now charges on peak concurrent users with prorated adjustment.
• October 6, 2025-Rebuilt platform launched with a new brand identity. “Benchmark Email Classic” stays on a separate login with no announced sunset, the two-product split that still causes documentation confusion.
• June 17, 2025-“What’s New at Benchmark: June 2025” release notes published, the last KB note located before the API rewrite.

Changelog content is split across product updates, the KB release notes and the Help Scout centre, and none is complete, product-updates surfaces nothing newer than Q1 2025.

Frequently asked questions