Flodesk API + MCP (2026): rebuilt v1, native MCP, no send endpoint

Flodesk spent most of its life without a usable public API, and that reputation is out of date. The developer API was rebuilt and relaunched in January 2026 at https://api.flodesk.com/v1, included on every paid plan at no extra cost, alongside a first-party Model Context Protocol server that makes Flodesk one of the few design-first ESPs with native AI-agent access. The catch is what it does not do: no send endpoint, no transactional surface and no SMTP relay anywhere in the product, so the API manages people and automations rather than messages.

The practical question is therefore not “does Flodesk have an API” but “can it do the thing I need”. Subscriber sync, segmentation, workflow entry, custom fields and webhooks: yes, cleanly. Receipts, password resets and app notifications: no, you will need a companion such as Postmark or Amazon SES on the same domain.

At a glance

MCP integration in 2026

Model Context Protocol lets an AI client such as Claude, ChatGPT or Gemini call a vendor’s tools directly instead of scraping a UI or being handed an API key in a prompt. For most marketing ESPs the 2026 answer is still “community wrappers only”. Flodesk is an exception.

Available MCP servers

One official server plus wrappers. The wrappers matter because they expose write actions the first-party server does not yet cover.

Flodesk API essentials

The v1 API is a small, conventional REST surface: JSON in, JSON out, HTTPS only, five resources, offset pagination. Nothing exotic to learn and nothing to work around, no GraphQL layer, no partial-response syntax, no bulk job queue beyond one batch endpoint.

Five resources carry the whole surface: subscribers (upsert, read, unsubscribe), segments (the list-equivalent, plus membership), workflows (list automations, push subscribers into them), custom fields and webhooks (full CRUD)-24 documented resource-and-method pairs. The mental model matters more than the count: a Flodesk segment is closer to a tag than a list, and an email only leaves the building when a subscriber crosses into a workflow you built in the visual editor. Your integration’s job is to get the right person into the right segment or workflow with the right custom fields attached.

Authentication methods

Two schemes, split by who owns the account you call on behalf of. Your own account: API key. Other people’s accounts, from a product you ship: OAuth2 plus Flodesk’s approval.

HTTP Basic with an API key

The private-integration path. Create a key in account settings, then send it as the username of an HTTP Basic credential with an empty password. The trailing colon is not optional, and omitting it is the most common cause of a 401 on a first request: the encoded value is base64("YOUR_API_KEY:"). Keys are shown exactly once at creation with no retrieval screen, so store yours in a secret manager before closing the dialog.

OAuth2 authorization code, for partner apps

Partner integrations use a standard authorization-code flow: authorize at https://api.flodesk.com/oauth2/authorize, exchange at https://api.flodesk.com/oauth2/token, resolve identity with GET /oauth2/userinfo. There is a single scope, all, granting full API access, no read-only variant exists, so least-privilege is not achievable through scoping. Refresh tokens are single-use: every refresh issues a new one and invalidates the old.

Rate limits

Two published limits, and the headline number is not the one that bites.

The workaround is planning, not engineering. A 100,000-contact migration at the batch ceiling needs at least 100 minutes of continuous, correctly-throttled calls before retries, so run it as a resumable background job with a checkpoint, not a request-scoped script that dies at the load balancer timeout. Read X-Fd-RateLimit-Remaining and slow down as it drops rather than sprinting into 429s. For one-off list moves, Flodesk’s CSV import beats any API path.

Official SDKs

There are none. Flodesk publishes no first-party client library in any language, maintains no public SDK repositories, and documents the API entirely with curl examples. This is a confirmed absence, not a documentation gap, and it says where the API sits on the roadmap: shipped and supported, not courted. The upside is that auth is plain HTTP Basic and payloads are flat JSON, so a working client is roughly 20 lines.

Notable community SDKs

No maintained, independently-published Flodesk client library could be verified against an official source as of August 2026. What exists instead are platform-level clients: the official Zapier app (3 triggers, 7 actions), the official Make app (10 modules, one of them a generic authenticated API call that reaches endpoints the others do not), Pabbly Connect and Pipedream. Those are the closest thing to an SDK with someone else maintaining the auth layer.

Endpoints reference

The fifteen below are the pairs an integration actually calls; the full reference is at developers.flodesk.com. Note what is absent and stays absent: anything named /messages, /send or /transactional.

Code examples

Verify credentials with curl

The fastest way to confirm a key works. Remember the trailing colon: the password half of the Basic credential is deliberately empty.

# Basic auth: API key as username, empty password.
curl -sS "https://api.flodesk.com/v1/segments?per_page=5" \
  -H "Authorization: Basic $(printf '%s:' "$FLODESK_API_KEY" | base64)" \
  -D - -o /dev/null

# 200 plus X-Fd-RateLimit-Limit: 100 and X-Fd-RateLimit-Remaining: 99.
# A 401 almost always means the colon after the key was omitted, or the
# account is on trial/free where API keys do not exist.

Python: upsert, segment, paginate

import requests
from requests.auth import HTTPBasicAuth

API_KEY = "your_flodesk_api_key"
BASE = "https://api.flodesk.com/v1"

# API key is the Basic-auth username; the password is an empty string.
auth = HTTPBasicAuth(API_KEY, "")

# 1. Create or update a subscriber (upsert on email)
r = requests.post(
    f"{BASE}/subscribers",
    auth=auth,
    json={"email": "reader@example.com", "first_name": "Alaa",
          "custom_fields": {"source": "smtpedia"}},
    timeout=30,
)
r.raise_for_status()
print(r.json()["id"])

# 2. Add them to a segment so your automation can pick them up
requests.post(
    f"{BASE}/subscribers/reader@example.com/segments",
    auth=auth,
    json={"segment_ids": ["YOUR_SEGMENT_ID"]},
    timeout=30,
).raise_for_status()

# 3. Page through subscribers (per_page max is 100)
page = 1
while True:
    resp = requests.get(f"{BASE}/subscribers", auth=auth,
                        params={"page": page, "per_page": 100}, timeout=30)
    if resp.status_code == 429:  # watch X-Fd-RateLimit-Remaining
        break
    resp.raise_for_status()
    rows = resp.json()["data"]
    if not rows:
        break
    for row in rows:
        print(row["email"])
    page += 1

# There is no endpoint to send an arbitrary email. To make Flodesk send,
# push the subscriber into a workflow built in the UI:
# POST /v1/workflows/{workflow_id}/subscribers

Node.js: batch upsert and workflow entry

// Node 18+ (built-in fetch). No official Flodesk SDK exists.
const BASE = "https://api.flodesk.com/v1";
const authHeader =
  "Basic " + Buffer.from(`${process.env.FLODESK_API_KEY}:`).toString("base64");

async function flodesk(path, options = {}) {
  const res = await fetch(`${BASE}${path}`, {
    ...options,
    headers: { Authorization: authHeader, "Content-Type": "application/json" },
  });
  if (res.status === 429)
    throw new Error(
      `Rate limited. Remaining=${res.headers.get("X-Fd-RateLimit-Remaining")}`
    );
  if (!res.ok) throw new Error(`Flodesk ${res.status}: ${await res.text()}`);
  return res.status === 204 ? null : res.json();
}

// 1. Batch upsert: up to 50 per call, 20 calls/min
await flodesk("/subscribers/batch", {
  method: "POST",
  body: JSON.stringify({
    subscribers: [
      { email: "a@example.com", first_name: "A" },
      { email: "b@example.com", first_name: "B" },
    ],
  }),
});

// 2. Trigger sending by entering a subscriber into a workflow
await flodesk(`/workflows/${process.env.FLODESK_WORKFLOW_ID}/subscribers`, {
  method: "POST",
  body: JSON.stringify({ subscriber_ids: ["SUBSCRIBER_ID"] }),
});

// There is no /messages or /send endpoint. Flodesk has no transactional API.

Common gotchas

Deprecations and changelog

Flodesk maintains no public changelog or release-notes feed for the API; developers.flodesk.com/changelog returns 403. The timeline below is reconstructed from Flodesk’s product blog and capability pages. Where the vendor states only a month, the entry is dated to the first of it.

• August 19, 2026-2026 plan structure confirmed: Free $0, Lite $19/mo annual, Pro $25/mo annual, Everything $49/mo annual at up to 1,000 subscribers. All integrations, MCP and API access included on every paid plan at no extra cost.
• January 2026-Native MCP server launched at https://mcp.flodesk.com/mcp, Flodesk positioning itself as one of the first email marketing platforms with one. Supports Claude, ChatGPT, Gemini and any MCP-compatible client.
• January 2026-Developer API rebuilt and relaunched at https://api.flodesk.com/v1, covering subscribers, segments, workflows, custom fields and webhooks, with API-key Basic auth for private integrations and OAuth2 for partners. Supersedes the earlier, effectively unavailable surface.
• August 26, 2025-Major platform release: ecommerce workflow triggers with 9 templates, subscription billing in Checkout via Stripe, team seats for up to 3 teammates, the Canva integration, and native integrations for ManyChat, HoneyBook, ThriveCart, Wix and Squarespace.

No API deprecations have been announced. The surface is path-versioned at /v1 and was rebuilt recently, so a breaking change should arrive as /v2 rather than in place, but with no changelog feed to subscribe to, monitor developers.flodesk.com directly and keep contract tests in CI.

Frequently asked questions