Loops API + MCP (2026): 47 paths, 5 SDKs, official MCP server

Loops ships one REST API at https://app.loops.so/api under a v1 prefix, an OpenAPI 3.1.0 document covering 47 paths, 5 SDKs, a CLI and, unusually for an email platform this size, a first-party Model Context Protocol server at https://mcp.loops.so. That server is the headline here. The API itself is conventional bearer-token JSON, with two documented absences: no pagination contract, no idempotency contract.

At a glance

The API still adds whole resource families every few weeks, and it is not a mature enterprise-contract API: no v2, no published deprecation window, no scoped credentials. Teams arriving from SendGrid or Mailgun should budget for that.

MCP integration in 2026

The Model Context Protocol is how an AI agent reaches a third-party product without a bespoke integration. Loops publishes a hosted server for it, which puts it in a small minority of email vendors.

A browser OAuth handshake means no long-lived key in an agent config file, and binds the connection to a person rather than a shared secret. The trade is that tool calls go to Loops infrastructure; there is no self-hosted build.

Why four meta tools instead of forty-seven

The server exposes 4 tools, not one per endpoint: Search finds the right API operation, Describe inspects its parameters, Execute runs it against a named team, Teams lists the teams the user can reach. Every REST call goes through Execute.

The design is unusual and correct here. One tool per endpoint would push 47 definitions, each with a full JSON Schema, into the agent’s context before the first user message is read, a large share of the window spent on definitions the agent never calls, with selection accuracy degrading as the list grows. Four tools cost almost nothing and stay constant.

The price is round trips: creating a contact means Search, then Describe, then Execute – 2 round trips before the first useful call, a third if Teams must resolve the team. Invisible interactively, costly in a high-frequency loop where you should call REST directly. The upside: when Loops added workflow endpoints in July 2026, no server release was needed for an agent to find them.

Installing the Loops MCP server

Commands as published by Loops. The Claude Code one installs at user scope, so the connector is available in every project.

# Claude Code
claude mcp add loops https://mcp.loops.so --scope user --transport http

# Codex CLI (v1.48.0 and later)
codex mcp add loops --url https://mcp.loops.so

For Claude Desktop, Loops sits under Settings › Connectors › Loops; for ChatGPT, in the plugin marketplace. The first call opens a browser window for the OAuth grant.

Available MCP servers

One official server, plus third-party wrappers reaching Loops through automation platforms. Those are not supported by Loops and cover whatever the wrapping platform exposes, typically a small subset of the 47 paths.

Loops API v1 essentials

The contract is small and conventional. The last two rows record what the documentation does not say.

Those are real absences, not omissions on our side: no cursor, page or limit parameter on any list endpoint, and no idempotency key header on any write endpoint. List contacts on a growing account and you have no guarantee how many rows return; a timed-out POST has no documented safe retry. Version against the prefix, never the build number.

Webhooks

Loops pushes events out over HTTP with a Standard Webhooks-shaped signature. Events cover the contact lifecycle (contact.created, contact.unsubscribed, contact.deleted, plus mailing list subscribe and unsubscribe), the send lifecycle (campaign.email.sent, loop.email.sent, transactional.email.sent) and the delivery lifecycle (email.delivered, email.softBounced, email.hardBounced, email.opened, email.clicked, email.unsubscribed, email.resubscribed, email.spamReported), plus testing.testEvent.

Verification is HMAC-SHA256 over id.timestamp.rawBody with a secret prefixed whsec_, using headers Webhook-Signature, Webhook-Id and Webhook-Timestamp. Sign the raw bytes before any JSON parsing, and compare in constant time. The payload carries eventName, webhookSchemaVersion 1.0.0 and eventTime.

Delivery is capped at 10 events per second, your endpoint must respond within 15 seconds, and Loops retries with exponential backoff up to 8 attempts across roughly 28 days. That generous window has a consequence: a four-week-old event can arrive after a newer one, so consumers must de-duplicate on Webhook-Id and never assume ordering. The timeout means enqueue and return, never process inline.

Authentication methods

One mechanism for the REST API, a different one for the MCP server. The split trips people up.

Bearer API key

Every REST call carries Authorization: Bearer YOUR_API_KEY, generated in the dashboard. A missing, malformed or revoked key returns 401. No HTTP Basic fallback, no query-string key, no signed-request scheme.

A dedicated endpoint confirms a key works: GET /v1/api-key returns success and teamName. That second field names the team whose data you are about to write to, catching the staging-key-in-production mistake before anything sends.

No OAuth on the REST API

This is the notable asymmetry. The MCP server authenticates with OAuth and a browser consent flow; the REST API does not offer OAuth at all. A product acting on your own users’ Loops accounts therefore has no authorisation-code flow, each customer generates and pastes a long-lived key, with the handling obligations that implies. Mailchimp and Klaviyo publish OAuth for this case. Loops does not.

Rate limits

Published, per team, enforced by rejection rather than queueing.

The consequence of that fifth row: client-side backoff is mandatory. The headers show remaining budget, but when a 429 lands nothing says when the window reopens. Retry immediately and you burn the next window; retry at a fixed interval across several workers and they synchronise into a thundering herd. Use exponential backoff with full jitter, from 1 second to about 30, plus a token bucket below 10 requests per second.

Limits are per team, not per key: a second key buys no throughput, and a batch importer shares its 10 requests per second with the live signup handler.

Official SDKs

Five official packages under the loops-so GitHub organisation, plus a CLI and agent skills.

The JavaScript SDK requires Node 18.0.0 or later, the only runtime floor Loops publishes.

There is no Python SDK

This is the gap that catches Django and FastAPI teams. Loops publishes no PyPI package and no Python client; the documented path is SMTP, with an official Django guide. One caveat, covered in full on this platform’s SMTP settings tab: that relay still expects an API-shaped payload carrying a transactionalId, so it is not a drop-in mail backend. For a native client, generate one from the OpenAPI document.

CLI and agent skills

The official CLI carries 17 subcommands – auth, contacts, campaigns, campaign-groups, audience-segments, components, contact-properties, email-messages, event-patterns, events, lists, themes, transactional, transactional-groups, uploads, workflows, completion – mapping onto the REST resource families, which makes it a fast way to explore the API before writing code. Loops also publishes agent skills: packaged instructions giving a coding agent working knowledge of the platform without a tool connection.

Endpoints reference

The 47 documented paths group into roughly a dozen resource families. The OpenAPI document is authoritative for the full list.

Contact paths are action-oriented, not collection-oriented, so code generators assuming REST conventions need the OpenAPI document. And the newest families are open alpha: isolate them behind your own interface.

Code examples

Two calls worth memorising: proving the key works, and sending one transactional email.

Verify an API key

Run this first in every environment: a 200 with a teamName you recognise means the key is live and aimed at the right team.

curl -s https://app.loops.so/api/v1/api-key \
  -H "Authorization: Bearer YOUR_API_KEY"

# { "success": true, "teamName": "Your Team" }
# A bad, revoked or missing key returns HTTP 401.

Send a transactional email

Transactional sends are addressed by template: you pass a transactionalId for a template that already exists, the recipient address, and a dataVariables object with the values the template interpolates. There is no way to send ad hoc content here.

curl -s -X POST https://app.loops.so/api/v1/transactional \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionalId": "YOUR_TRANSACTIONAL_ID",
    "email": "customer@example.com",
    "dataVariables": {
      "firstName": "Ada",
      "resetUrl": "https://example.com/reset/abc123"
    }
  }'

The official JavaScript SDK wraps the same call as sendTransactionalEmail with an identical argument object, on Node 18.0.0 or later.

Wrap both in a retry that backs off on 429, and treat the transactionalId as configuration: template IDs differ between staging and production, and a hardcoded one is the commonest cause of a reset email rendering the wrong template.

Common gotchas

Deprecations and changelog

The current quarter of the official changelog, newest first. The pattern is a platform adding whole resource families rather than refining existing ones.

• July 23, 2026 – audience segment creation, workflow management and event pattern read endpoints added.
• July 16, 2026 – workflow responses guarantee a non-null rootNodeId.
• July 8, 2026 – create and update endpoints for themes and components.
• July 2, 2026 – Guardian endpoint launched, validating message content through the API.
• July 1, 2026 – transactionalName added to transactional webhook events.
• June 22, 2026 – workflow read and node retrieval endpoints, in open alpha.
• June 19, 2026 – campaign endpoints extended with targeting, groups and scheduling; CC, BCC and language added to email messages.
• June 5, 2026 – transactional email create and edit endpoints, in open alpha.

No deprecations are listed, and Loops publishes no policy on how much notice a breaking change gets. With two families in open alpha, follow the official API changelog rather than waiting to be told.

Frequently asked questions