@thenavidm/flodesk-mcp-cli

v3.0.0

Published

a month ago

Flodesk shared MCP and task CLI for current subscribers, native batch upserts, draft campaigns, workflows, custom fields, webhooks and exact reviewed account work.

Flodesk MCP Server & CLI

Flodesk MCP server and CLI for Codex and AI agents. 32 shared tools for current subscribers, draft campaigns, workflows, custom fields and webhooks, private account profiles and exact reviewed subscriber batches.

One package provides a task CLI, local stdio MCP and versioned desktop bundle. Built and maintained by Navid Moazzez. Built on Slipway, which turns one definition of each tool into the MCP server and the CLI. Complete setup: navid.me.

The terminal illustrates actual commands, not a recorded provider account session. Node 22+ is required for manual installs; private account API access, subscription eligibility and audience permissions remain separate.

Two ways to use it

Command line

A terminal or shell agent calls only the requested task.

npx -y --package @thenavidm/flodesk-mcp-cli@latest flodesk-cli list-accounts --agent

MCP server, for your AI app

codex mcp add flodesk --env FLODESK_TOKEN_FILE=/absolute/private/flodesk.txt -- npx -y @thenavidm/flodesk-mcp-cli@latest

Which one

Use task-specific CLI help/compact output for terminal automation, or local MCP for your AI client. Both enforce the exact same handlers and policy. Complete setup is in INSTALL.md.

Features

Current native 50-subscriber upsert and complete current subscriber/segment arguments.
Correct native DELETE JSON, workflow enrollment/removal and actual draft-campaign exports.
Native custom-field and webhook management with explicit approval.
Shared read-only/direct-call guard, isolated Basic/Bearer profiles and exact ordered reviews.
Full client/OS/desktop setup, native terminal, version history, accurate official comparison and 20 FAQ accordions.

| Section | What it covers | | --- | --- | | 1. What you can ask it | What you can ask it | | 2. Quick install | Quick install | | 3. Set up Flodesk access | Set up Flodesk access | | 4. Connect your client | Connect your client | | 5. Check it works | Check it works | | 6. Output, flags and exit codes | Output, flags and exit codes | | 7. MCP or CLI and token cost | MCP or CLI and token cost | | 8. Every tool and argument | Every tool and argument | | 9. Subscriber, draft and automation workflows | Subscriber, draft and automation workflows | | 10. Exact reviewed batches and pagination | Exact reviewed batches and pagination | | 11. Several private accounts | Several private accounts | | 12. Writing safely | Writing safely | | 13. How the two surfaces work | How the two surfaces work | | 14. Your data | Your data | | 15. Environment variables | Environment variables | | 16. Updates and removal | Updates and removal | | 17. Troubleshooting | Troubleshooting | | 18. API coverage and comparisons | API coverage and comparisons | | 19. Versions and migration | Versions and migration | | 20. FAQ | FAQ |

1. What you can ask it

Read the intended account's subscribers, current native statuses and one exact subscriber.
Create/update only approved subscriber data, native batch upserts and segment membership.
Inspect workflows, enroll/remove exactly requested subscribers and account for email side effects.
Manage requested custom fields and webhook configuration with native arguments.
Publish a reviewed Canva/Studio export as a draft campaign, without sending it.
Review ordered subscriber operations and save a requested single audience page privately.

Actual shared discovery exposes 32 tools: 16 reads and 16 confirmed operations. All 20 legacy tool names remain. Six current REST additions and six helper/account/file/batch tasks complete the shared catalogue. See actual native arguments, major migrations and current official comparison below. The official hosted MCP has separate analytics and cohort capabilities this package does not invent.

2. Quick install

npm install -g @thenavidm/flodesk-mcp-cli@latest
flodesk-cli --version
flodesk-cli tools
flodesk-cli schema batch-create-or-update-subscribers
flodesk-cli login

Node 22+ for manual CLI/local MCP. INSTALL.md has Codex first and full client/OS setup, including the versioned desktop bundle.

3. Set up Flodesk access

Private integration API key

Sign into the intended Flodesk account. Open Account → Integrations → API, or the API key settings. Check which account owns the audience before creating/copying a key.
Use a private integration API key for your own account. The native docs describe full API access; this package does not invent per-operation key scopes or guarantee provider read-only keys. Local read-only policy is a separate control.
Save FLODESK_API_KEY only in private user/client environment settings, or use FLODESK_TOKEN_FILE as an absolute token-only file outside repositories. On macOS/Linux use a private 0700 directory and owner-private 0600 regular non-symlink file, at most 64 KiB. On Windows restrict file/parent ACLs to yourself; POSIX mode checks do not establish Windows ACLs.
Run flodesk-cli doctor for local settings. Deliberately run doctor --network to read one subscriber page with per_page=1; output reports only count, not the subscriber record. That verifies one read, not account-owner identity, campaign/webhook access or all native permissions.
Inspect exact native fields and IDs, then approve only requested work. Double opt-in, segment additions and workflow enrollment can trigger actual messages. Do not create subscribers, opt-ins, workflow entries, drafts or webhooks merely to test installation.

The API key is an HTTP Basic username, with an empty password. The client constructs Authorization: Basic base64(key:), sends a descriptive User-Agent and uses only the allowlisted https://api.flodesk.com origin. No API key goes into a URL, prompt, Git file or log. It refuses redirects and unknown routes.

Externally minted partner OAuth

Native partner OAuth requires a provider-approved integration with its own client ID/secret and redirect flow. This package accepts an externally minted FLODESK_ACCESS_TOKEN or named access_token profile as Authorization: Bearer. It does not register an app, start login, exchange authorization codes, refresh tokens or import official connector sessions.

Access tokens are documented as 24 hours; refresh tokens are single-use and rotate. Refreshing belongs to your approved private integration and must store its newly issued refresh token securely. This runtime never holds that client secret/refresh token. Restart after replacing its access token. get_oauth_userinfo makes only the fixed /oauth2/userinfo GET and refuses API-key profiles before any request.

For a token file containing an OAuth access token, set FLODESK_AUTH_TYPE=oauth for a direct profile, or auth_type:"oauth" in that named profile. File credentials otherwise default to API key. Never configure api_key and access_token together. A selected file overrides only its own profile's inline credential; profiles never inherit a global key/token or another account.

Several private accounts

FLODESK_ACCOUNTS is a private JSON array of unique {name,api_key,access_token,token_file,auth_type} entries. Choose exactly one credential type in each. FLODESK_DEFAULT_ACCOUNT and --account select exact labels. Labels and review hashes are not verified provider ownership. Token files cache until process restart. list_accounts returns only labels/default/auth type/credential source, without token paths or provider reads.

Official MCP connection

Flodesk already supplies its official MCP and setup help. Its production field reference currently lists 35 tools, including email/form/checkout/workflow analytics, cohort filters, subscriber actions, CSV export and bulk archive/unarchive/segment changes. Its previews issue single-use confirmation tokens expiring after 120 seconds. Those capabilities and safeguards already exist.

The September 11 help article describes an earlier 24-tool/individual-action phase and says bulk work is upcoming; the current production catalog describes 35 tools and bulk workflows. Treat that as documented source drift. Marketing's broad future-control examples do not establish current send/schedule support. This local public-REST package does not call private MCP-only analytics/cohort routes or accept the hosted connector's confirmation tokens.

Quotas and effects

The AGPL wrapper is free; Flodesk subscription/API eligibility and account policies remain separate. Native REST limits are 100 requests/minute normally and 20/minute for POST /subscribers/batch, up to 50 subscribers per request. X-Fd-RateLimit headers report remaining capacity. Our process spacing defaults 650 ms, plus a separate 3100 ms batch window. Other processes/apps share account quota; local pacing is not provider enforcement or a guaranteed distributed limiter.

No automatic retries, including reads, 429, 5xx, redirects or timeouts. A failed write can leave an unknown result, duplicate webhook/segment or triggered message. Inspect provider state before deliberately repeating. JSON requests cap 1 MiB and responses 5 MiB. Each native list returns one page with its own meta/page semantics, not an all-pages backup. Workflow statuses use native CSV and perPage; campaign query names retain native capitalization.

Canva and Studio publish draft campaign exports, not send/schedule emails. Subscriber upsert can create or update by id/email; up to 50 segment IDs are supported. double_optin applies only to newly created subscribers and can send a confirmation message. Workflow re-entry needs prior completion and Allow repeat subscribers; abandoned-cart workflows cannot be enrolled through this route. Unsubscribe changes subscription state without pretending to delete the record. Removing segment membership is distinct and sends the required native DELETE JSON body.

Revocation and retained data

Revoke the intended key at Flodesk, replace private settings/files and restart. Revoke partner OAuth/official connector authorization separately. Package/client removal does not undo audience changes, sent opt-ins/workflow effects, drafts, webhooks or private audience-page files. Retain receipts and investigate unknown outcomes before explicitly requested cleanup.

4. Connect your client

INSTALL.md covers Codex, Claude Code, Claude Desktop bundle/manual stdio, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Cline, Docker and other local stdio clients on macOS/Windows/Linux. No Claude Code installation is needed for Codex. GUI/remote runtimes need their own private settings and accessible file paths; restart/reconnect after changes.

This owned package is local stdio. Official hosted connectors use their own authentication/settings. Manual/client configurations must keep credentials outside project Git; optional SKILL.md is not installed automatically by npm.

codex mcp add flodesk --env FLODESK_TOKEN_FILE=/absolute/private/flodesk.txt -- npx -y @thenavidm/flodesk-mcp-cli@latest

5. Check it works

flodesk-cli --version
flodesk-cli tools
flodesk-cli list-accounts --agent
flodesk-cli doctor
flodesk-cli doctor --network
flodesk-cli list-subscribers --per-page 1 --agent --select meta,data.id

The release validates shared full/read-only discovery and native request fixtures. Actual authenticated provider reads/writes, desktop GUI installation and matched successful Codex task/token measurements require their own evidence. doctor without --network checks local configuration only. One successful subscriber read does not prove ownership or every permission; never trigger opt-ins/workflows to test installation.

6. Output, flags and exit codes

Native provider JSON/meta is preserved after recognized credential redaction. Audience records, draft HTML and emails can still contain private data. --select filters only the needed fields locally. save_subscriber_page writes one confirmed page exclusively into a private JSON file and returns saved-file metadata, not customer rows.

Native batch upserts can return HTTP 200 with successes and failures. Inspect both arrays; a 2xx transport status is not complete success. Workflow enrollment returns native acceptance/data; it does not prove messages completed. All requests happen once; provider state must resolve unknown outcomes before any repeat.

Use --payload or an absolute private --payload-file for full native bodies, mutually exclusive with flat body flags and each other. Primitive array flags repeat one value at a time; --subscribers and --tasks repeat individual JSON objects. The house bridge derives flag names from actual schema, including native campaign query capitalization and workflow perPage.

flodesk-cli list-subscribers --per-page 5 --agent --select meta,data.id
flodesk-cli list-workflows --help
flodesk-cli schema publish-studio-email

| Flag | Behavior | | --- | --- | | --agent | Compact JSON and no prompts; never confirms a write | | --confirm | Explicit requested-operation approval | | --account LABEL | Exact private key/token profile | | --select a,b.c | Local field selection | | --payload / --payload-file | Complete exclusive native body input | | --subscribers JSON | Repeat native batch-upsert item objects | | --tasks JSON | Repeat ordered local review objects | | --review-sha256 HASH | Exact matching ordered preview hash | | --output-file PATH | New exclusive private page file |

| Exit | Meaning | | --- | --- | |0|Handler/receipt success; still inspect partial native failures| |1|Unexpected error| |2|Invalid arguments, a refused or unapproved operation, an unknown command or a hidden write| |3|Not found| |4|Auth/permission| |5|API/network/unknown write outcome| |7|Provider rate limit| |10|Missing/invalid private configuration|

7. MCP or CLI and token cost

Both surfaces are built by Slipway from the exact same real tool catalogue, handlers, argument validation and write guard. CLI discovery/task-specific help can expose only requested command information; MCP clients determine their own discovery/loading strategy. No statement here assumes every client sends every schema on every turn.

Measured on 2026-10-05 against 2.0.2, with Claude Code 2.1.286 on Claude Opus 5.5 (one short prompt with and without the server connected, the difference read from the API's own usage figures) and Codex 0.159.3 on gpt-6.1-sol:

| Cost | 2.0.2 | 3.0.0 | | --- | --- | --- | | Claude Code, every tool loaded, every message | 13,410 | 12,750 | | Claude Code's default, tool search, every message | 949 | 950 | | SKILL.md, read once | 1,232 | 1,289 | | Codex over the CLI, one task, median of five | 126,029 | 82,830 | | Codex over MCP, the same task, median of five | 48,151 | 48,158 |

The task was "find the command that adds a subscriber to a segment, and the flags it requires". Every tool loaded costs less because a subscriber batch and the double opt-in switch, each written out twice as their own arguments and inside payload, are now written once and referred to. Over the CLI, four of five 2.0.2 runs tried a command that failed, a bare schema or one that does not exist, then read the whole command list, because 2.0.2's help never said how to list commands; every extra step carries the whole conversation forward. Every 3.0.0 run asked which and read one command's help. Over MCP, Codex prints its own TypeScript rendering of the tool list and keeps its first and last 20,000 characters or so: the whole rendering is 182 tokens shorter on 3.0.0, but the part Codex keeps holds about 43 more, which each later request carries. SKILL.md costs 57 more because it now says how approval works over MCP and lists every exit code.

| Evidence | Current status | | --- | --- | | Actual shared full/read-only discovery | Verified release checks | | Local mutation/read-only/account/partial-request behavior | Verified fixtures, no provider side effects | | Official hosted authenticated task comparison | Not measured; documentation scope only |

Tool-list bytes or characters divided by four are not API usage, and no other offering was measured.

8. Every tool and argument

`list_campaigns`

List campaigns.

Kind: Read. Native account permissions and local semantics still apply.

`publish_canva_email`

Publish a Canva email design as a draft campaign.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | bundle_url | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | title | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | design_token | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | page_id | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | campaign_id | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.payload

`get_canva_design_state`

Get the latest Canva design state for auto-selecting campaigns.

Kind: Read. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. |

`publish_studio_email`

Publish a Studio email export as a draft campaign.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | html | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | title | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | campaign_id | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | asset_id | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.payload

`list_custom_fields`

List all custom fields (pagination).

Kind: Read. Native account permissions and local semantics still apply.

`create_custom_field`

Create a custom field.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | label | No; body/guard requirements still apply | string | A friendly display label of the custom field. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | label | Yes | string | A friendly display label of the custom field. |

`list_all_custom_fields`

List all custom fields.

Kind: Read. Native account permissions and local semantics still apply.

`list_segments`

List all segments.

Kind: Read. Native account permissions and local semantics still apply.

`create_segment`

Create a segment.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | color | No; body/guard requirements still apply | string | The color of the segment using a hex code. Use GET List all segment colors. to view available colors. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.payload

`list_segment_colors`

List all segment colors.

Kind: Read. Native account permissions and local semantics still apply.

`get_segment`

Retrieve a segment.

Kind: Read. Native account permissions and local semantics still apply.

`list_subscribers`

List all subscribers.

Kind: Read. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | page | No; body/guard requirements still apply | integer | The page number. Defaults to 1. minimum: 1. maximum: 9007199254740991. format: "int64". | | per_page | No; body/guard requirements still apply | integer | The number of records to be returned on each page. Defaults to 20. Maximum 100. minimum: 1. maximum: 100. format: "int64". | | status | No; body/guard requirements still apply | string | Optional. The subscriber's status. active: The subscriber is currently active to receive marketing emails. unsubscribed: The subscriber has opted out of marketing emails. unconfirmed: The subscriber is pending for double opt-in confirmation. bounced: The subscriber's address is undeliverable due to a hard bounce. complained: The subscriber marked an email as spam. cleaned: The subscriber was cleaned, learn more here. archived: The subscriber was archived. enum: ["active", "unsubscribed", "unconfirmed", "bounced", "complained", "cleaned", "archived"]. | | segment_id | No; body/guard requirements still apply | string | Optional. The segment's id. When included, returns only subscribers who were added to the given segment. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. |

`create_or_update_subscriber`

Create or update a subscriber.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | No; body/guard requirements still apply | string | The subscriber's id. Either email or id must be included. | | email | No; body/guard requirements still apply | string | The subscriber's email. Either email or id must be included. | | first_name | No; body/guard requirements still apply | string | The subscriber's first name. | | last_name | No; body/guard requirements still apply | string | The subscriber's last name. | | custom_fields | No; body/guard requirements still apply | object | An object containing custom field data. E.g. "favorite_color": "Lavender". | | segment_ids | No; body/guard requirements still apply | array | The segments this subscriber will be added to. Cap at 50. | | double_optin | No; body/guard requirements still apply | boolean | Whether or not to require the subscriber to confirm subscription via email. This option is only available to set with new subscriber creation. Default to false if not indicated. | | optin_ip | No; body/guard requirements still apply | string | IP address from which the subscriber confirmed their opt-in. | | optin_timestamp | No; body/guard requirements still apply | string | The date and time the subscribers confirmed their opt-in in ISO 8601 format. E.g. 2023-01-02T15:04:05.999Z. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.custom_fields

input.custom_fields.{key}

Native JSON value; inspect the full schema for validation.

input.segment_ids

input.segment_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.custom_fields

input.payload.custom_fields.{key}

Native JSON value; inspect the full schema for validation.

input.payload.segment_ids

input.payload.segment_ids[]

Native JSON value; inspect the full schema for validation.

`batch_create_or_update_subscribers`

Create or update up to 50 subscribers in a single request.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | subscribers | No; body/guard requirements still apply | array | List of subscribers to create or update. Maximum 50 items. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.subscribers

input.subscribers[]

input.subscribers[].custom_fields

input.subscribers[].custom_fields.{key}

Native JSON value; inspect the full schema for validation.

input.subscribers[].segment_ids

input.subscribers[].segment_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | subscribers | Yes | array | List of subscribers to create or update. Maximum 50 items. |

input.payload.subscribers

input.payload.subscribers[]

input.payload.subscribers[].custom_fields

input.payload.subscribers[].custom_fields.{key}

Native JSON value; inspect the full schema for validation.

input.payload.subscribers[].segment_ids

input.payload.subscribers[].segment_ids[]

Native JSON value; inspect the full schema for validation.

`get_subscriber`

Retrieve a subscriber.

Kind: Read. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id_or_email | Yes | string | Exact native path parameter. minLength: 1. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. |

`remove_subscriber_from_segments`

Remove the subscriber from segments.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id_or_email | Yes | string | Exact native path parameter. minLength: 1. | | segment_ids | No; body/guard requirements still apply | array | An array of identifiers of the segments. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.segment_ids

input.segment_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | segment_ids | Yes | array | An array of identifiers of the segments. |

input.payload.segment_ids

input.payload.segment_ids[]

Native JSON value; inspect the full schema for validation.

`add_subscriber_to_segments`

Add the subscriber to segments.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.segment_ids

input.segment_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | segment_ids | Yes | array | An array of identifiers of the segments. |

input.payload.segment_ids

input.payload.segment_ids[]

Native JSON value; inspect the full schema for validation.

`unsubscribe`

Unsubscribe from all lists.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

`list_webhooks`

List all webhooks.

Kind: Read. Native account permissions and local semantics still apply.

`create_webhook`

Create a webhook.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | No; body/guard requirements still apply | string | The webhook name. | | post_url | No; body/guard requirements still apply | string | The url that the webhook will post to. | | events | No; body/guard requirements still apply | array | An array specifying which events are enabled for webhook notifications. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.events

input.events[]

Native JSON value; inspect the full schema for validation.

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | name | Yes | string | The webhook name. | | post_url | Yes | string | The url that the webhook will post to. | | events | Yes | array | An array specifying which events are enabled for webhook notifications. |

input.payload.events

input.payload.events[]

Native JSON value; inspect the full schema for validation.

`delete_webhook`

Delete a webhook.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | Yes | string | Exact native path parameter. minLength: 1. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |

`get_webhook`

Retrieve a webhook.

Kind: Read. Native account permissions and local semantics still apply.

`update_webhook`

Update a webhook.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | Yes | string | Exact native path parameter. minLength: 1. | | name | No; body/guard requirements still apply | string | The webhook name. | | post_url | No; body/guard requirements still apply | string | The url that the webhook will post to. | | events | No; body/guard requirements still apply | array | An array specifying which events are enabled for webhook notifications. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.events

input.events[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.events

input.payload.events[]

Native JSON value; inspect the full schema for validation.

`list_workflows`

List workflows.

Kind: Read. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | statuses | No; body/guard requirements still apply | array | filter by workflow statuses e.g. statuses=active,paused. Default is all statuses | | page | No; body/guard requirements still apply | integer | Default = 1 minimum: 1. maximum: 9007199254740991. format: "int64". | | perPage | No; body/guard requirements still apply | integer | Default = 10 Local positive integer validation; perPage has a local 100-item cap. minimum: 1. maximum: 100. format: "int64". | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. |

input.statuses

input.statuses[]

Native JSON value; inspect the full schema for validation.

`add_subscriber_to_workflow`

Notes:

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | workflow_id | Yes | string | Exact native path parameter. minLength: 1. | | id | No; body/guard requirements still apply | string | id is required if email is not present | | email | No; body/guard requirements still apply | string | email is required if id is not present | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | payload | No; body/guard requirements still apply | object | Complete native JSON body; do not mix with body flags or payload_file. Arrays use repeated JSON object flags or a whole native array in a private file. | | payload_file | No; body/guard requirements still apply | string | Absolute regular non-symlink JSON body file, at most 1 MiB. Cannot mix with payload/body flags. minLength: 1. |

input.payload

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | No; body/guard requirements still apply | string | id is required if email is not present | | email | No; body/guard requirements still apply | string | email is required if id is not present |

`remove_subscriber_from_workflow`

Remove a subscriber from workflow.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | workflow_id | Yes | string | Exact native path parameter. minLength: 1. | | id_or_email | Yes | string | Exact native path parameter. minLength: 1. | | account | No; body/guard requirements still apply | string | Exact configured private account profile label; not a tenant or provider account ID. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. |

`list_accounts`

Local profile labels/default/auth method only. No keys, token paths, provider identity or network request.

Kind: Read. Native account permissions and local semantics still apply.

Native JSON value; inspect the full schema for validation.

`get_operation_schema`

Local reviewed method/path/query/body schema and provenance for one native tool. No credentials or provider request.

Kind: Read. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | operation | Yes | string | Exact native tool name, e.g. batch_create_or_update_subscribers or publish_studio_email. enum: ["list_campaigns", "publish_canva_email", "get_canva_design_state", "publish_studio_email", "list_custom_fields", "create_custom_field", "list_all_custom_fields", "list_segments", "create_segment", "list_segment_colors", "get_segment", "list_subscribers", "create_or_update_subscriber", "batch_create_or_update_subscribers", "get_subscriber", "remove_subscriber_from_segments", "add_subscriber_to_segments", "unsubscribe", "list_webhooks", "create_webhook", "delete_webhook", "get_webhook", "update_webhook", "list_workflows", "add_subscriber_to_workflow", "remove_subscriber_from_workflow"]. |

`get_oauth_userinfo`

One fixed UserInfo GET for an explicitly selected externally minted OAuth access token. API keys refuse; no refresh, OAuth login or fallback.

Kind: Read. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | account | No; body/guard requirements still apply | string | Exact selected private account profile; binds label, not key ownership. |

`preview_subscriber_batch`

Local validation and SHA-256 of exact ordered subscriber/segment/workflow/custom-field work, selected profile label and reviewed schema. No provider reads, key load, identity check, price or rollback guarantee.

Kind: Read. Native account permissions and local semantics still apply.

input.tasks

input.tasks[]

| Argument | Required | Type | Details | | --- | --- | --- | --- | | tool | Yes | string | Native field; use the reviewed provider reference. enum: ["create_custom_field", "create_segment", "create_or_update_subscriber", "batch_create_or_update_subscribers", "remove_subscriber_from_segments", "add_subscriber_to_segments", "unsubscribe", "add_subscriber_to_workflow", "remove_subscriber_from_workflow"]. | | arguments | Yes | object | Actual native tool arguments without account, confirm, payload_file or output_file. |

`submit_subscriber_batch`

Confirmed one-to-twenty ordered subscriber/segment/workflow/custom-field tasks. Prevalidate all and verify exact hash before first request. Stop on first failure with known results/failed index/unattempted indices; no retries, rollback or implicit continuation.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | tasks | Yes | array | One to twenty exact ordered supported subscriber/segment/workflow/custom-field operations. Native batch upserts may affect up to50 subscribers per task; not a20-person budget. minItems: 1. maxItems: 20. | | account | No; body/guard requirements still apply | string | Exact selected private account profile; binds label, not key ownership. | | confirm | No; body/guard requirements still apply | boolean | Set true only when the user asked for exactly this action. | | review_sha256 | Yes | string | Exact preview_subscriber_batch hash for identical requests, profile label, schema and order. pattern: "^[a-f0-9]{64}$". |

input.tasks

input.tasks[]

`save_subscriber_page`

Confirmed one-page GET saved only to an exclusive new0600 JSON file. No CSV/cohort export, all-pages loop, overwrite, automatic upload or browser preview.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

Native list_campaigns: GET /campaigns

List campaigns.

No JSON body.

Native publish_canva_email: POST /campaigns/canva

Publish a Canva email design as a draft campaign.

Native JSON value; inspect the full schema for validation.

Native body: | Argument | Required | Type | Details | | --- | --- | --- | --- | | bundle_url | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | title | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | design_token | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | page_id | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | campaign_id | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. |

Native get_canva_design_state: GET /campaigns/canva/design-state

Get the latest Canva design state for auto-selecting campaigns.

Native JSON value; inspect the full schema for validation.

No JSON body.

Native publish_studio_email: POST /campaigns/studio

Publish a Studio email export as a draft campaign.

Native JSON value; inspect the full schema for validation.

Native body: | Argument | Required | Type | Details | | --- | --- | --- | --- | | html | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | title | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | campaign_id | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | asset_id | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. |

Native list_custom_fields: GET /custom-fields

List all custom fields (pagination).

No JSON body.

Native create_custom_field: POST /custom-fields

Create a custom field.

Native JSON value; inspect the full schema for validation.

Native body: | Argument | Required | Type | Details | | --- | --- | --- | --- | | label | Yes | string | A friendly display label of the custom field. |

Native list_all_custom_fields: GET /custom-fields/all

List all custom fields.

Native JSON value; inspect the full schema for validation.

No JSON body.

Native list_segments: GET /segments

List all segments.

No JSON body.

Native create_segment: POST /segments

Create a segment.

Native JSON value; inspect the full schema for validation.

Native body: | Argument | Required | Type | Details | | --- | --- | --- | --- | | name | No; body/guard requirements still apply | string | Native field; use the reviewed provider reference. | | color | No; body/guard requirements still apply | string | The color of the segment using a hex code. Use GET List all segment colors. to view available colors. |

Native list_segment_colors: GET /segments/colors

List all segment colors.

Native JSON value; inspect the full schema for validation.

No JSON body.

Native get_segment: GET /segments/{id}

Retrieve a segment.

| Argument | Required | Type | Details | | --- | --- | --- | --- | | id | Yes | string | Exact native path parameter. minLength: 1. |

No JSON body.

Native list_subscribers: GET /subscribers

List all subscribers.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Flodesk MCP Server & CLI

Two ways to use it

Command line

MCP server, for your AI app

Which one

Features

Contents

1. What you can ask it

2. Quick install

3. Set up Flodesk access

Private integration API key

Externally minted partner OAuth

Several private accounts

Official MCP connection

Quotas and effects

Revocation and retained data

4. Connect your client

5. Check it works

6. Output, flags and exit codes

7. MCP or CLI and token cost

8. Every tool and argument

list_campaigns

publish_canva_email

get_canva_design_state

publish_studio_email

list_custom_fields

create_custom_field

list_all_custom_fields

list_segments

create_segment

list_segment_colors

get_segment

list_subscribers

create_or_update_subscriber

batch_create_or_update_subscribers

get_subscriber

remove_subscriber_from_segments

add_subscriber_to_segments

unsubscribe

list_webhooks

create_webhook

delete_webhook

get_webhook

update_webhook

list_workflows

add_subscriber_to_workflow

remove_subscriber_from_workflow

list_accounts

get_operation_schema

get_oauth_userinfo

preview_subscriber_batch

submit_subscriber_batch

save_subscriber_page

Native list_campaigns: GET /campaigns

Native publish_canva_email: POST /campaigns/canva

Native get_canva_design_state: GET /campaigns/canva/design-state

Native publish_studio_email: POST /campaigns/studio

Native list_custom_fields: GET /custom-fields

Native create_custom_field: POST /custom-fields

Native list_all_custom_fields: GET /custom-fields/all

Native list_segments: GET /segments

Native create_segment: POST /segments

Native list_segment_colors: GET /segments/colors

Native get_segment: GET /segments/{id}

Native list_subscribers: GET /subscribers

`list_campaigns`

`publish_canva_email`

`get_canva_design_state`

`publish_studio_email`

`list_custom_fields`

`create_custom_field`

`list_all_custom_fields`

`list_segments`

`create_segment`

`list_segment_colors`

`get_segment`

`list_subscribers`

`create_or_update_subscriber`

`batch_create_or_update_subscribers`

`get_subscriber`

`remove_subscriber_from_segments`

`add_subscriber_to_segments`

`unsubscribe`

`list_webhooks`

`create_webhook`

`delete_webhook`

`get_webhook`

`update_webhook`

`list_workflows`

`add_subscriber_to_workflow`

`remove_subscriber_from_workflow`

`list_accounts`

`get_operation_schema`

`get_oauth_userinfo`

`preview_subscriber_batch`

`submit_subscriber_batch`

`save_subscriber_page`