MCP Server

Sendly runs a remote Model Context Protocol server. Point an MCP-capable AI client at it, choose what it may do, and the agent can work in your Sendly account directly — answering which domains are verified, tidying your contacts, diagnosing why a message did not arrive, building and pausing your automations, drafting the next campaign, and, if you say so, sending it.

Endpoint

https://app.sendly.now/api/mcp

The transport is Streamable HTTP. Authorization is OAuth 2.1 with PKCE, or a Sendly secret key.

Sendly is listed in the official MCP registry as now.sendly/sendly. The listing is metadata only — the endpoint above, the transport it speaks, and the optional Authorization header — because Sendly is a remote server: there is nothing to install and no package to download. A client that finds Sendly through the registry connects to exactly the URL you would otherwise paste in by hand.

Connect

Claude Code

claude mcp add --transport http sendly https://app.sendly.now/api/mcp

The first tool call opens a browser to Sendly, where you sign in and choose the permissions. After that the connection persists.

Setting up a different agent — Codex, Cursor, Windsurf, OpenCode, or VS Code/Copilot? See Onboard your agent for the exact command per client, or paste the agent-setup prompt into the agent itself and let it run the setup.

Claude (web and desktop)

Add Sendly as a custom connector in your Claude settings, using the endpoint URL above. Custom connectors are available on Claude's paid plans; your Claude workspace's own policy decides whether members may add them.

Any other MCP client

Sendly works with any client that speaks Streamable HTTP and supports the OAuth authorization-code flow with PKCE. Give the client the endpoint URL — there is no application to pre-register. The client discovers everything it needs and registers itself automatically:

The issuer is https://app.sendly.now/api/auth. Dynamic client registration is open, so a client that has never talked to Sendly before can still register and start the flow unattended. Path-inserted aliases of both documents are served as well, so clients that derive the metadata URL either way will find it.

Connecting with an API key

Put the key on the Authorization header and skip the OAuth flow entirely:

claude mcp add --transport http sendly https://app.sendly.now/api/mcp \  --header "Authorization: Bearer sk_…"

A key connection differs from an OAuth one in three ways worth knowing:

• The key's own scopes are the agent's permissions. Whatever you ticked when you created the key is what the agent gets — there is no second consent screen. With one documented exception: a handful of tools need a signed-in person rather than a project, because the routes behind them identify a project admin from the user. Those are never offered to a key connection whatever you ticked — create_project, create_mailbox, delete_mailbox, and all four API-key tools. Use an OAuth connection for those.
• It is bound to one project. The key's project is the target of every call, and a projectId argument that disagrees is refused with PROJECT_FIXED rather than quietly ignored. To act on another project, use a key belonging to it.
• It is a project credential, not a personal one. It does not appear in Settings → Connected apps, because there is no consent row behind it. You revoke it from Settings → API keys, and revocation stops the agent on its next call.

Choosing what an agent can do

Both screens that ask you to grant capability — the OAuth consent screen and the API-key dialog — open on a named preset and then let you tick individual boxes. A preset is just a starting selection; nothing is stored except the resulting list of permissions.

Standard access is the default, and it is deliberately a capable grant: an agent that manages your contacts, segments, templates and campaign drafts, and that cannot put mail in anyone's inbox. Most people want that and nothing more.

A grant with no permissions ticked is valid. It means the client can sign you in and learn nothing else.

Connecting a read-only agent

Read only is the preset to reach for when an agent should answer questions about a project and change nothing in it. Two consequences are worth knowing before you choose it, and the server enforces both rather than merely documenting them.

• The tool list is shorter. Tools are filtered against the connection's permissions before the agent is shown anything, so a read-only connection is never offered send_campaign, create_contact or edit_workflow at all. It cannot call what it cannot see, and it does not spend a turn discovering a refusal.
• diagnose_delivery is offered. Deliverability has a read permission of its own, which is what lets the question people ask an agent most — why did this email not arrive? — be answerable without granting a single write.

Two permissions are deliberately outside it. api-keys:read enumerates your credentials, so it belongs in no pre-ticked preset: a read-only agent may see your contacts, but not what your keys are allowed to do. And emails:test sits in Standard access instead, because "read only" is a promise about the world rather than about our database — a preset that sends mail, even to you, has broken the promise its name makes.

Permissions that need explicit approval

Nine permissions can produce an effect that nothing in the Sendly dashboard undoes. They render unchecked, with the warning below shown next to the box:

Two of these are worth explaining, because they are the ones people query. api-keys:read changes nothing — it is on the list for what it reveals, since a map of which credentials exist and what each may do is a map of your account's attack surface. And campaigns:write is not on the list: drafting a campaign and mailing it are separate permissions now, so an agent can build a campaign for you without being able to send it.

Code Mode (default)

A connection sees exactly two tools, not one per operation: search_tools and execute_typescript. Every capability in Full surface below still exists behind them, reachable the same way, under the same permissions — this changes how many tools a client lists, not what an agent can do.

Calling external_<name>(...) from inside the program reaches the identical handler a direct call to that tool would run: the same auth, scope, project-selection, mass-send-confirmation and audit checks, whether the agent called it by name or through execute_typescript. Orchestrating three calls in one program costs one MCP round trip instead of three; it does not do anything three separate tool calls could not.

search_tools declares only the tools this connection's permissions reach. Any other external_* name is simply not defined inside the program, so calling one throws a ReferenceError rather than a coded refusal.

A refusal inside the program — a project it may not target, a revoked connection, an unconfirmed mass send, arguments that do not match the declaration — surfaces as a thrown JavaScript Error, not as a separate result shape: the message reads <CODE>: <details>, for example CONFIRMATION_REQUIRED: … or INVALID_ARGUMENTS: …, using the same codes as Troubleshooting below. When the refusal carries structured fields (requiredScope, upstreamCode, upstreamStatus), they follow the details as trailing JSON, for example TOOL_EXECUTION_FAILED: … {"upstreamCode":"CONFLICT","upstreamStatus":409}. The program's own try/catch sees it like any other exception, and the outer tool call is not marked as an error — the call itself succeeded; the code the agent wrote is what failed. A program that runs for roughly 30 seconds, an infinite loop included, is stopped and the call still answers normally, reporting that it did not finish rather than hanging.

If a client cannot orchestrate a sandboxed program at all, Sendly can serve the one-tool-per-operation surface below directly instead (MCP_TOOL_SURFACE=full) — an operational switch, not something a connection asks for itself.

Full surface

The one-tool-per-operation surface execute_typescript orchestrates above, and the one Sendly can also serve directly. An agent only sees the tools its grant covers here too: if you approve analytics:read and nothing else, view_analytics and list_projects are the only tools below that appear — the others are never registered, so the agent cannot even attempt them.

Your projects

Contacts and segments

Templates and sending domains

Email

send_test_email is how an agent proves sending works without being able to mail anyone. It takes no from argument — the sender is the project's sandbox address, and the route refuses a body that names one — and there is a daily cap on sandbox sends. It is a member of Standard access, which is why that preset can confirm your setup end to end while still being unable to put mail in a stranger's inbox.

Campaigns

Workflows

manage_workflow has exactly two actions, pause and resume. Reading a workflow's state used to be a third one and is now get_workflow_status, which is a permissions fact rather than tidying: a tool declares one permission and must be able to reach everything it does, pausing needs workflows:write, and reading the run counts needs only workflows:read. Left as one tool, the read action would have been refused for exactly the connections granted write without read. Split, an agent that may look but not touch can still answer "is this automation running, and how many contacts are inside it".

Building a workflow's steps

create_workflow and edit_workflow take a linear list of steps, which is what almost every automation is. The trigger step is prepended for you — do not include it — and passing steps to edit_workflow replaces every existing step rather than merging, which is why that tool is marked destructive.

Anything with a branch is a graph rather than a sequence, and graphs are read and written whole at GET and PUT /api/v1/workflows/{id}/graph — workflows:read and workflows:write respectively. A GET response is accepted verbatim by PUT on the same path, so the round trip is: read the document, change one step, send it all back.

{
  "workflow_id": "8f1c4d2e-5a7b-4a1e-9c3f-2b6d8e0a1f42",
  "version": 7,
  "steps": [
    {
      "id": "1b9f6a30-2c44-4f8e-9a01-77c2d1b5e903",
      "type": "TRIGGER",
      "name": "Signed up",
      "position": { "x": 0, "y": 0 },
      "config": { "eventName": "user.signup" },
      "template_id": null
    },
    {
      "id": "3d2e7c81-9b05-4a26-8f13-0c5a4e9d6712",
      "type": "DELAY",
      "name": "Wait a day",
      "position": { "x": 0, "y": 160 },
      "config": { "amount": 1, "unit": "days" },
      "template_id": null
    },
    {
      "id": "5a4b8e12-6d37-4c90-b2e5-1f8c3a70d954",
      "type": "SEND_EMAIL",
      "name": "Day 1: getting started",
      "position": { "x": 0, "y": 320 },
      "config": {},
      "template_id": "c7e1a904-3b62-4d58-8a17-9e05f2d6b481"
    }
  ],
  "transitions": [
    {
      "id": "9c0d5f73-1a86-42be-9d47-6b3e8a15c027",
      "from_step_id": "1b9f6a30-2c44-4f8e-9a01-77c2d1b5e903",
      "to_step_id": "3d2e7c81-9b05-4a26-8f13-0c5a4e9d6712",
      "condition": null,
      "priority": 0
    },
    {
      "id": "2e6a1b48-7f39-4c05-a8d2-53b90c7e6f18",
      "from_step_id": "3d2e7c81-9b05-4a26-8f13-0c5a4e9d6712",
      "to_step_id": "5a4b8e12-6d37-4c90-b2e5-1f8c3a70d954",
      "condition": null,
      "priority": 0
    }
  ]
}

Send that same document back to PUT to keep the workflow as it is, or change it first. The rules the document follows:

• Step ids are yours. Send back an id you read to keep that step and its run history, a fresh UUID to add a step, and omit a step entirely to delete it along with its history.
• Exactly one step is the TRIGGER — the graph's single entry node.
• config is typed per step type, across the nine types TRIGGER, SEND_EMAIL, DELAY, WAIT_FOR_EVENT, CONDITION, EXIT, WEBHOOK, UPDATE_CONTACT and SEND_AT_OPTIMAL_TIME. Because the contract discriminates on type, a generated SDK narrows config from the type you already know. A key the contract does not name is passed through rather than deleted; a key whose value is wrong — unit: "fortnights", a webhook target that is not a URL — is rejected.
• Every edge stays inside the document. from_step_id and to_step_id must name steps in the same payload, and a step may not point at itself. priority orders the edges leaving one step, lowest first. A CONDITION step's edges carry { "branch": "yes" } and { "branch": "no" }, or the branch's id in the multi-branch form.
• At most 200 steps and 400 transitions.
• version moves on every structural write, and each write snapshots the graph, so a different number between two reads means somebody edited it in between.
• A graph write is refused with a 409 while the workflow has runs in flight, because those contacts are standing on the steps being replaced. POST /api/v1/workflows/{id}/pause clears them first.

For a linear sequence you do not need these endpoints at all: POST /api/v1/workflows and PATCH /api/v1/workflows/{id} both accept a sequence, which is exactly what create_workflow and edit_workflow send, so the two credentials build the same graph rather than similar ones.

POST /api/v1/workflows/{id}/clone — the route behind clone_workflow — copies a workflow and its whole graph server-side, from one consistent read. That is not the same as reading a graph and writing it into a new workflow: a copy assembled from two requests can capture an edit that landed between them and materialise a workflow that never existed.

Analytics and usage

Deliverability

Every signal in the answer was already readable one endpoint at a time. What no endpoint did was say what the combination means, which is the part a support conversation actually turns on: "verified, but SPF failing and 6% bouncing" is a different problem from "not verified", and telling them apart from three separate payloads was a judgement the caller had to make unaided.

So the answer leads with findings — worst first, each one a stable code, a severity of blocking, degraded or info, what is wrong, and the fix. An agent branches on the code, never on the wording. The codes are domain_not_registered, domain_not_verified, recipient_suppressed, spf_failing, dmarc_missing, custom_mail_from_failed, bounce_rate_critical, bounce_rate_elevated, complaint_rate_critical, complaint_rate_elevated, no_recent_sends, sample_too_small_for_rates and dns_never_checked.

Two things to read the raw signals with. The DNS statuses are the cached results of Sendly's verification job rather than a live lookup, and identity.last_checked_at says when they were filled. The delivery counters are the project's, over a window of 1 to 30 days that defaults to 7, because an email record does not store which domain sent it.

It has a permission of its own rather than riding on domains:read, because it reads DNS state, delivery counters and suppression together, and a key granted "view your sending domains" did not agree to the last of those. Nothing under it writes anything or reveals anything a project member cannot already see in the dashboard, so it is pre-ticked from Read only upwards.

Cleaning a list

These are billed per address checked, which is why the write permission is its own box rather than part of contacts:write: an agent allowed to manage your contacts should not be able to spend your money by looping over your list. Reading a finished run costs nothing and sits in Read only.

Every answer carries a verdict, and it is the field to branch on. deliverable is safe to mail. undeliverable means the domain does not exist or publishes no MX records. risky means a throwaway-inbox provider. unknown means DNS did not answer, so that address was not checked — it is a separate value from undeliverable on purpose, because an agent that merged the two would remove live contacts over a network hiccup.

The other fields describe the address rather than judge it. is_personal (a free consumer provider) and is_role_address (support@, info@) are list-quality information, not problems: real customers use Gmail and real companies answer their support address. is_disposable is the only flag that lowers a verdict.

clean_list cleans nothing by itself. It validates and stops — no membership is unsubscribed and no contact is deleted. Acting on a finding is a separate call under a different permission, which is what stops a DNS lookup that can answer unknown from quietly shrinking an audience.

Subscriber lists

A list is static membership: people who were put on it and stay until they leave. That is what separates it from a segment, which is a live condition over contact fields, and from a topic, which is a standing decision about a subject. member_count counts memberships in every status — a pending invitation and an unsubscribed opt-out are both memberships — so it is the size of the membership table, not the number of people a send would reach.

Adding people to a list is not on this surface. Subscribing is where double opt-in begins: it creates the membership as pending and mints a confirmation token whose delivery is your job. An agent putting someone on a list would be asserting a consent it has no evidence of, so the tools stop at the list itself.

delete_list deletes the consent record. The memberships go with the list, and an unsubscribed membership is the evidence that somebody opted out — re-creating the list and re-importing the same addresses will not find their opt-outs waiting. The mail already sent is untouched.

Topics and consent

A topic is a subject you mail about — a weekly digest, a changelog, a billing notice — and a contact's answer to one is a standing decision rather than an audience filter. It applies whatever audience a campaign selects, so choosing a different audience is not a way around it. That is the difference between a preference centre and a checkbox nobody honours.

set_topic_subscription cannot subscribe anybody. Asking it to subscribe parks the contact at pending and hands back a confirmation link; nothing is mailed on that topic until a person opens it, and there is no parameter to skip the step. An agent asserting that somebody wants mail is not evidence that they do, and the reputation the mistake costs is yours. Sendly does not send that confirmation email — you do, from your own verified domain. Unsubscribing is the other way round and takes effect at once: withdrawing consent must never be harder than giving it.

default_opt_in decides what SILENCE means. Left true, a contact who has never answered counts as subscribed — which is the honest reading for a topic introduced over a list you already have, since those people consented to hear from you. Set false, absence means "not asked" and only an explicit yes counts. subscribed_count reports explicit answers only, so it reads low on a default_opt_in topic; that is how many people answered, not how many would receive the mail.

There is no delete. archived: true retires a topic — it leaves the preference centre and stops being mailable — and every opt-out recorded against it survives, because deleting the topic would delete the choices people made about it.

Events and webhooks

Suppression list

Mailboxes

Mailboxes are the conversational side: a real inbox behind an address like support@yourdomain.com, so mail sent there arrives in Sendly — and, with its own permission, an agent can write and send a new message from that address.

Five facts about these that are easier to know now than to discover later:

• No agent tool reads a mailbox's messages. The mail a mailbox receives is third-party correspondence, and no permission in the vocabulary covers reading it. get_mailbox returns the connection settings, never the contents.
• A mailbox cannot be changed after it is created. There is no update route and no update tool — deliberately. To change an address, delete the mailbox and create the one you want.
• Quotas are not supported. Mailboxes are created with no storage limit and there is no way to add one afterwards. The tool does not offer the argument, and the route refuses it rather than accepting a value it would never apply.
• The domain must be verified first, and a project may hold at most ten mailboxes. Both are refused with a 409, not silently worked around.
• Drafting and sending are different permissions. compose_mailbox_email only needs mailboxes:read because it changes nothing: it hands the agent text to show you. Putting that text in someone's inbox as your support address is send_mailbox_email under mailboxes:send, which is separate from emails:send on purpose — an agent trusted to send a receipt from your verified domain has not thereby been trusted to open a conversation as your support desk. It arrives unchecked, and a well-behaved agent shows you the draft and confirms the recipients before calling it.

API keys

An agent can create and rotate keys, and it still never sees a secret — see Tools that hand you a link below for how that works. Two limits are worth stating plainly:

• A new key cannot be broader than the connection that made it. create_api_key requires an explicit list of permissions, and any permission the connection does not itself hold is refused with SCOPE_ESCALATION. The request is rejected outright, never quietly trimmed to fit — so an agent cannot use api-keys:write to manufacture a capability you never granted it. Only your own dashboard session is exempt, because a project admin already has full authority over their own project.

• Every tool in this section needs an OAuth connection. All four API-key routes identify a project admin from the signed-in user, and an API key carries no user, so a key connection could never call one. They are therefore not offered to a key connection at all — absent from its tool list rather than failing when it tries. This is a designed property, not a failure mode: a tool an agent cannot use should not be in its list. An agent connected with a key cannot list, create, rotate or revoke keys.

  list_api_keys is the one that looks out of place, so it is worth saying why it is here. This rule is about the shape of the route, not about danger: api-keys:read is not one of the permissions needing explicit approval, and merely reading is not irreversible, yet the route still requires a signed-in user and so the tool still cannot be used by a key. Every other tool withheld in this guide is withheld because of what it can do; this one is withheld because of who it needs to be.

Tools that hand you a link

Three tools cannot finish inside the agent, and answer with status: "action_required" and a URL for you to open instead of a result:

For the two key tools the reason is that a secret must never enter a tool result. Anything an agent receives is written into the model's context, the client's transcript, and every log that transcript passes through — a permanent credential in all three. So the secret does not cross the boundary at all. Instead the link is a single-use, five-minute ticket, and opening it requires a signed-in Sendly session belonging to an admin of the project — a credential no agent has, and one an OAuth token or an API key cannot produce. The agent that asked for the key cannot read it, including the one that just broke your deployment by rotating it. Holding the URL is not enough on its own, and a link opened by the wrong person is spent rather than honoured, so if that happens, rotate again.

start_domain_setup uses the same shape for a different reason: publishing DKIM, SPF and MX records happens at your registrar, where Sendly has no credentials and never will.

Permissions and consent

During the OAuth flow, Sendly shows you a consent screen listing exactly what the client is asking for, with a checkbox each. These are the descriptions you will read:

Nothing happens on your account until you approve, and no tool ever runs under a permission you did not grant.

Every permission in this table has at least one endpoint behind it, so nothing you grant here is inert. Two of them have no AGENT TOOL yet: lists:read and lists:write govern the /api/v1/lists endpoints, which an API key or an OAuth token can call directly, and the MCP surface does not offer a list tool. Granting them to an agent connection today therefore widens what a token could do over HTTP and changes nothing the agent itself can reach — which is worth knowing before you tick them.

Choosing a project

Every tool except list_projects operates on one project.

• An OAuth connection covers every project you belong to, and each tool takes an optional projectId. Belong to exactly one? Leave it out; Sendly infers it. Belong to several? The agent must pass one, or the call is refused with PROJECT_REQUIRED and told to call list_projects first. Well-behaved agents do this on their own. A projectId that is not one of your projects gets the same PROJECT_REQUIRED before the tool does anything, worded identically whether that project exists or not.
• An API-key connection is bound to the key's own project. The argument is not offered at all, and a client that sends one anyway is refused with PROJECT_FIXED.

Sendly refuses rather than guessing in both cases on purpose: silently picking "the first" project, or silently ignoring a projectId the agent believed it was acting on, would mean acting on the wrong tenant's data.

Changing your mind

To withdraw one permission, go to Settings → Connected apps and untick it. The connection stays; the agent keeps everything else.

To end the connection entirely, choose Disconnect on the same page. For a key connection, revoke the key in Settings → API keys instead.

Troubleshooting

Failures come back to the agent as tool results carrying a code, not as transport errors, so the agent can explain them to you rather than just dropping the connection.

How it relates to the rest of the platform

The MCP server is not a separate backend. Every tool call goes out over Sendly's own public REST API carrying the same credential you connected with, so the same scope checks, membership rules, and project-disabled rules apply to an agent as to curl or the SDKs. There is no privileged shortcut.