Sendly MCP
Envía correos transaccionales, ejecuta campañas y gestiona contactos, listas y segmentos en Sendly. Servidor remoto con inicio de sesión OAuth.
Servidor MCP alojado
npx add-mcp 'https://app.sendly.now/api/mcp'Se instala en Claude Code, Codex, Cursor y más
Documentación
MCP Server (/guides/mcp)
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.
The consent screen groups permissions into a handful of rows, and **every row arrives checked** — untick what the agent should not do. Permissions that cannot be undone — sending mail, revoking an API key, taking an address off your suppression list — carry a plain sentence naming the consequence, and the agent has to **confirm each of those calls once** before it runs. Any permission can be withdrawn later without disconnecting.Endpoint [#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 [#connect]
Claude Code [#claude-code]
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) [#claude-web-and-desktop]
One click: Add Sendly to Claude opens Sendly's listing in Claude's connector directory; click Connect, then sign in. Or add Sendly as a custom connector in your Claude settings by hand, 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 [#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:
| Discovery document | URL |
|---|---|
| Protected-resource metadata (RFC 9728) | https://app.sendly.now/.well-known/oauth-protected-resource |
| Authorization-server metadata (RFC 8414) | https://app.sendly.now/.well-known/oauth-authorization-server |
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.
Connect from any MCP client [#connect-from-any-mcp-client]
Sendly's MCP server is a hosted Streamable HTTP endpoint with OAuth 2.1 sign-in. There is nothing to install or run: point the client at the URL below and sign in to Sendly when the browser opens. Every client that supports remote MCP servers with OAuth works; the ones below are the common ones.
https://app.sendly.now/api/mcp
Claude (claude.ai, Claude Desktop, Claude Code) [#claude-claudeai-claude-desktop-claude-code]
- claude.ai / Claude Desktop: one click: Add Sendly to Claude opens Sendly's listing in Claude's connector directory; click Connect, then sign in. By hand: Settings → Connectors → Add custom connector, paste the URL, then sign in. Custom connectors are available on Claude's paid plans.
- Claude Code: the command above, then
/mcpto sign in.
ChatGPT and Codex [#chatgpt-and-codex]
- ChatGPT: one click: Open Sendly in ChatGPT opens Sendly's published ChatGPT app; click Connect, then sign in. Manual: Settings → Apps & Connectors → Create (developer mode), name it Sendly, paste the URL, authentication OAuth.
- Codex CLI: add to
~/.codex/config.toml:
[mcp_servers.sendly]
url = "https://app.sendly.now/api/mcp"
Cursor [#cursor]
One click: Add to Cursor. Or in .cursor/mcp.json:
{ "mcpServers": { "sendly": { "url": "https://app.sendly.now/api/mcp" } } }
VS Code and GitHub Copilot [#vs-code-and-github-copilot]
One click: Add to VS Code. Or run MCP: Add Server → HTTP and paste the URL, which writes to .vscode/mcp.json:
{ "servers": { "sendly": { "type": "http", "url": "https://app.sendly.now/api/mcp" } } }
Google Antigravity [#google-antigravity]
Install the plugin from the repository (or from the Antigravity Marketplace once listed):
agy plugin install https://github.com/DevinoSolutions/mcp-servers/antigravity-plugins/sendly
Or add the server by hand in ~/.gemini/config/mcp_config.json (Antigravity requires the serverUrl key):
{ "mcpServers": { "sendly": { "serverUrl": "https://app.sendly.now/api/mcp" } } }
Gemini [#gemini]
- Gemini app: Settings → Connected apps → Custom apps → Add a custom app, paste the URL, then mention
@Sendlyin a chat. (Custom apps are currently limited to personal Google accounts in the US.) - Gemini CLI:
gemini extensions install https://github.com/DevinoSolutions/mcp-serversthen/mcp auth sendly, or add{ "mcpServers": { "sendly": { "httpUrl": "https://app.sendly.now/api/mcp" } } }to~/.gemini/settings.json.
Kiro [#kiro]
One click: Add to Kiro. Or in .kiro/settings/mcp.json:
{ "mcpServers": { "sendly": { "url": "https://app.sendly.now/api/mcp" } } }
Perplexity, Mistral Le Chat, Grok [#perplexity-mistral-le-chat-grok]
- Perplexity (Pro, Max, Enterprise): Settings → Connectors → Custom connector, paste the URL, authentication OAuth.
- Mistral Le Chat (all plans): Intelligence → Connectors → Add Connector → Custom MCP Connector, paste the URL.
- Grok: grok.com → Connectors → New connector → Custom, paste the URL.
Other clients [#other-clients]
- Replit: Add to Replit, or Integrations → Add MCP server.
- Devin, Windsurf, Zed, JetBrains Junie, Cline, OpenCode: add a remote (HTTP) MCP server with the URL above; each prompts for the OAuth sign-in on first use. Cline can also install it from the Cline marketplace entry using its
llms-install.md.
Tokens are scoped to what you approve on the consent screen; a tool you did not grant is never shown to the assistant. Revoke access at any time from Settings → Connected apps. A client connected with a secret key instead of OAuth (see Connecting with an API key) is revoked from Settings → API keys.
Connecting with an API key [#connecting-with-an-api-key]
Put the key on the Authorization header and skip the OAuth flow entirely:
<DynamicCodeBlock lang="bash" code="claude mcp add --transport http sendly https://app.sendly.now/api/mcp \\n --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: some tools need a signed-in person rather than a project, because the routes behind them identify you, or a project admin, from the user. Those are never offered to a key connection whatever you ticked: creating, changing, resetting or deleting projects, creating or deleting mailboxes and app passwords, the API-key tools, API usage and request logs, your referral, billing changes and invoices, your profile, preferences, exports and account deletion, members, connected apps and Slack, appeals, and the organization views. Use an OAuth connection for those.
- It is bound to one project. The key's project is the target of every call, and a
projectIdargument that disagrees is refused withPROJECT_FIXEDrather 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 [#choosing-what-an-agent-can-do]
Both screens that ask you to grant capability — the OAuth consent screen and the API-key dialog — show one checkbox row per kind of action, and every row arrives checked. Each row expands into the individual permissions under it; untick a row, or one permission inside it, and what gets saved is the resulting list of permissions.
| Row | Permissions | Warning shown |
|---|---|---|
| Read your data | 25 | None |
| Create and edit | 15 | None |
| Delete, publish or send | 4 | Can delete or publish data. We keep backups — contact support to restore anything removed by mistake. |
| Billing and subscription | 1 | Can start a purchase, cancel or refund your subscription. |
| Profile, preferences, account deletion | 1 | Can delete this account. Signing in again within 30 days cancels the deletion. |
| Members and invites | 1 | None |
| Connected services | 1 | None |
| Support tickets | 1 | None |
| API keys | 1 | None |
An OAuth connection covers every project you belong to; the agent names the project on each call. Deleting, sending and billing changes are not just warned about: the agent must confirm each such call once with a single-use token before it runs.
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 [#connecting-a-read-only-agent]
Leave only Read your data ticked 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_contactoredit_workflowat all. It cannot call what it cannot see, and it does not spend a turn discovering a refusal. diagnose_deliveryis 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.
api-keys:read sits in that row but carries its own warning, because it enumerates your
credentials: untick it if a read-only agent may see your contacts but not what your keys
are allowed to do. And emails:test sits in Create and edit instead, because "read" is
a promise about the world rather than about our database — a row that sends mail, even to
you, has broken the promise its name makes.
Permissions that carry a warning [#permissions-that-carry-a-warning]
Fifteen permissions can produce an effect that nothing in the Sendly dashboard undoes. They arrive checked like every other permission, with the warning below shown next to the box:
| Permission | What you are warned about |
|---|---|
emails:send | Mail sent this way reaches real inboxes and cannot be recalled. |
campaigns:send | This sends a campaign to your whole audience and cannot be recalled. |
workflows:write | An enabled workflow keeps sending on its own, long after this conversation. |
suppression:write | Removing an address lets Sendly mail someone who asked you to stop. |
projects:write | New projects count towards your plan and may be billed; deleting or resetting one erases its data. |
api-keys:read | Reveals which keys exist and what each one can do. |
api-keys:write | A key created here keeps working even after you disconnect this app. |
mailboxes:write | A new mailbox starts receiving real mail on your domain, and deleting one erases every message it holds. |
mailboxes:send | Mail sent this way arrives from your own support address and cannot be recalled. |
mailbox-conversations:read | Gives this app the private email people have sent you, and what it has read cannot be taken back. |
mailbox-conversations:reply | A reply goes out from your own address to the person who wrote to you, and cannot be recalled. |
billing:write | Can start a purchase, cancel or refund your subscription. |
account:write | Can delete this account. Signing in again within 30 days cancels the deletion. |
members:write | Can remove people from your projects. |
connections:write | Can disconnect Slack and revoke connected AI apps. |
The two mailbox-conversation permissions are different from the others in one more way:
no key created before them holds them, including a legacy full-access key — those keys
keep the permissions they were created with. A new key or connection starts with them
checked, like every other permission it was offered. They are separate from each other and
from mailboxes:send, so an agent can be allowed to read a support inbox without being
allowed to answer anyone in it.
Two of the others 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) [#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.
| Tool | What it does |
|---|---|
search_tools | Finds the tools this connection can reach and returns each as a declare function external_<name>(...) TypeScript signature, labelled [read-only] or [write] with its title and description. An optional query argument narrows the result to a case-insensitive substring match against a tool's name, title or description — it narrows what the connection can already reach, and never widens it. Omit it to list everything reachable. |
execute_typescript | Runs a short TypeScript program, written by the agent, in an isolated sandbox. The program calls the external_* functions search_tools declared — they are already in scope — and must return its result. await Promise.all([...]) runs independent calls in one round trip instead of several. |
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,
retryAfterSeconds), 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.
ChatGPT is the one exception. Its app lists every tool in Full surface by
name, without search_tools and execute_typescript, so ChatGPT calls each operation
directly. Every other client sees the two tools above.
Full surface [#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 [#your-projects]
| Tool | What it does | Permission |
|---|---|---|
list_projects | List the projects this connection can act in. Use it to choose the projectId for other tools. | none |
list_granted_scopes | What this connection may do: its permissions, the groups they make up, and the groups it lacks | none |
request_scopes | Ask you for more permission groups. Answers a one-time link; nothing changes until you approve | none |
get_project | The active project's settings: name, sending region, link-tracking mode, whether it is disabled | projects:read |
create_project | Create a new project on your account. OAuth connections only — an API key has no user to add as a member | projects:write |
update_project | Rename the project or change its tracking, language or sending region. OAuth connections only | projects:write |
delete_project | Delete the project and everything in it. Asks the agent to confirm first. OAuth connections only | projects:write |
reset_project | Erase the project's data but keep the project, its domains and its keys. Asks the agent to confirm first. OAuth connections only | projects:write |
get_project_setup_state | Which onboarding steps the project has finished | projects:read |
get_project_security | The project's sending health and any suspension | projects:read |
get_audit_log | Who changed what in the project, newest first | projects:read |
Organizations [#organizations]
An organization groups your projects. Every figure covers only the projects you are a member of, and these tools act for you, so they work over OAuth connections only.
| Tool | What it does | Permission |
|---|---|---|
list_orgs | The organizations you belong to, with your role in each | projects:read |
get_org_overview | Sending volume, delivery rates and inbox load across an organization's projects | projects:read |
refresh_org | Recompute an organization's overview figures now. Admins only | projects:write |
list_org_mailboxes | The mailboxes across an organization's projects, with what each still needs | mailboxes:read |
list_org_inbox_mailboxes | The mailboxes the organization-wide inbox covers, grouped by project | mailboxes:read |
list_org_inbox_conversations | Conversations across every mailbox you can open in the organization, newest first | mailbox-conversations:read |
get_org_inbox_counts | Unread and open conversation counts per mailbox | mailbox-conversations:read |
Contacts and segments [#contacts-and-segments]
| Tool | What it does | Permission |
|---|---|---|
list_contacts | List contacts, optionally filtered by email or subscription status | contacts:read |
get_contact | One contact, with its custom fields | contacts:read |
create_contact | Add a contact | contacts:write |
update_contact | Edit a contact's fields or subscription status | contacts:write |
delete_contact | Remove a contact | contacts:write |
upsert_contact | Create a contact, or update it when the address is already there | contacts:write |
lookup_contacts | Find contacts by email address, up to 500 at a time | contacts:read |
import_contacts | Import contacts from CSV text, up to 5 MB; it runs in the background | contacts:write |
export_contacts | A one-time link that downloads the project's contacts as CSV | contacts:read |
bulk_create_contacts | Create up to 1000 contacts in one call | contacts:write |
bulk_set_subscription | Subscribe or unsubscribe up to 1000 contacts | contacts:write |
bulk_delete_contacts | Delete up to 1000 contacts by id or by address. Asks the agent to confirm first | contacts:write |
purge_contact | Erase one contact and its history for good, and never mail the address again. Asks the agent to confirm first | contacts:write |
bulk_purge_contacts | The same erasure for up to 1000 contacts. Asks the agent to confirm first | contacts:write |
list_contact_fields | The custom fields the project's contacts use | contacts:read |
get_contact_field_usage | Which segments, templates and workflows use a custom field | contacts:read |
list_contact_field_values | The distinct values stored in a custom field | contacts:read |
delete_contact_field | Remove a custom field from every contact. Asks the agent to confirm first | contacts:write |
list_contact_events | The events recorded for one contact, newest first | events:read |
get_suppression | Whether one address is suppressed, and why | suppression:read |
list_segments | List segments | segments:read |
get_segment | One segment and its condition | segments:read |
list_segment_contacts | Who currently matches a segment | segments:read |
create_segment | Create a segment | segments:write |
update_segment | Edit a segment's condition | segments:write |
delete_segment | Delete a segment | segments:write |
compute_segment | Recalculate who matches a segment, in the background | segments:write |
refresh_segment | Recount a segment's members now | segments:write |
add_segment_members | Add addresses to a static segment, optionally creating missing contacts | segments:write |
remove_segment_members | Remove addresses from a static segment; the contacts stay | segments:write |
Templates and sending domains [#templates-and-sending-domains]
| Tool | What it does | Permission |
|---|---|---|
list_templates | List email templates | templates:read |
get_template | One template, with its body | templates:read |
create_template | Create a template | templates:write |
update_template | Edit a template | templates:write |
delete_template | Delete a template that no workflow or unsent campaign uses. Asks the agent to confirm first | templates:write |
duplicate_template | Copy a template | templates:write |
get_template_usage | Which campaigns and workflows use a template | templates:read |
list_template_versions | A template's saved versions | templates:read |
revert_template | Restore a template to an earlier version | templates:write |
list_snippets | Reusable content blocks templates can include | templates:read |
get_snippet | One snippet and its content | templates:read |
create_snippet | Save a reusable content block | templates:write |
update_snippet | Edit a snippet | templates:write |
delete_snippet | Delete a snippet. Asks the agent to confirm first | templates:write |
upload_image | Host an image from a public URL or base64 bytes and answer its URL | templates:write |
check_domain | Verification status of your sending domains | domains:read |
add_domain | Register a sending domain and return the DNS records to publish | domains:write |
verify_domain | Re-check a domain's DNS records and persist the result | domains:write |
get_domain_logo | Read a sender logo, its BIMI record and live DNS readiness | domains:read |
upload_domain_logo | Replace a domain's sender logo with sanitized vector SVG | domains:write |
start_domain_setup | Begin guided DNS setup and return a link you open to publish the records at your registrar | domains:write |
get_domain | One sending domain: DNS records, verification state, stream and region | domains:read |
update_domain_stream | Assign a domain to transactional or marketing mail, make it the default, set its default sender | domains:write |
delete_domain | Remove a sending domain; mail from it stops at once. Asks the agent to confirm first | domains:write |
get_domain_connect_status | Whether the domain's DNS provider supports one-click setup | domains:read |
get_domain_warmup | Where a new domain is in its warm-up ramp, and today's sending | domains:read |
manage_domain_warmup | End a domain's warm-up early, or start it again | domains:write |
get_domain_logo_readiness | What each inbox provider still needs before it shows the domain's logo | domains:read |
delete_domain_logo | Remove a domain's sender logo | domains:write |
Email [#email]
| Tool | What it does | Permission |
|---|---|---|
list_emails | The emails you have sent, with delivery status | emails:read |
get_email | One email and its events | emails:read |
send_test_email | Send a test message from the project's sandbox address. It can only reach the project owner's own verified account email — any other recipient is refused. A new project gets 20 free test emails before it needs a domain | emails:test |
send_email | Send a transactional email. Reaches a real inbox and cannot be recalled | emails:send |
send_batch_emails | Send up to 100 transactional emails in one call, with a result per email. Asks the agent to confirm first | emails:send |
reschedule_email | Move a still-pending email to a new send time, or send it now. Asks the agent to confirm first | emails:send |
cancel_scheduled_email | Cancel a still-pending email before it is sent. Asks the agent to confirm first | emails:send |
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 in the Create and edit row, which is why an agent without the send row can confirm your setup end
to end while still being unable to put mail in a stranger's inbox.
A new project gets 20 free test emails this way, with no domain, no DNS and no billing.
Each result carries test_allowance (limit, used, remaining), so the agent knows how
many are left. When they run out, the call is refused with upstreamCode: quota_exhausted
and next: add_domain: adding and verifying the project's own domain is what lifts the
limit (a verified domain sends on the free plan, no card needed). After that, test sends
meet only the daily cap, and test_allowance is null.
Campaigns [#campaigns]
| Tool | What it does | Permission |
|---|---|---|
list_campaigns | List campaigns | campaigns:read |
get_campaign | One campaign | campaigns:read |
get_campaign_stats | A campaign's delivery and engagement numbers | campaigns:read |
create_campaign | Create a campaign draft | campaigns:write |
update_campaign | Edit a draft or scheduled campaign's content or audience | campaigns:write |
manage_campaign | Cancel, pause, or resume a campaign | campaigns:write |
delete_campaign | Delete a campaign | campaigns:write |
send_campaign | Send or schedule a campaign to its full audience. Cannot be recalled once sending starts | campaigns:send |
duplicate_campaign | Copy a campaign as a new draft | campaigns:write |
send_campaign_test | Send one test copy of a campaign to a member of the project; any other address is refused | emails:test |
list_campaign_failures | The recipients a campaign failed to reach, with the reason for each | campaigns:read |
retry_failed_campaign_sends | Queue a campaign's failed sends again; bounced and suppressed addresses are skipped | campaigns:write |
The token is bound to the caller, the tool and the exact arguments, lasts ten minutes and works once, so one "yes" cannot be spent on a different send or on a second one. The guard is server-side for a reason: Sendly can ask your client to confirm through the protocol, but this endpoint keeps no session, so that request reaches nobody, and a guard whose only enforcement lives in the client is not a guard.
Through execute_typescript, the second call has to come from a new program. A token
presented in the same program that received it is refused with CONFIRMATION_REQUIRED
before anything runs, so an agent cannot catch the refusal and confirm its own call without
asking you. The token is not used up by that refusal: it still works, once, from the next
execute_typescript call.
Workflows [#workflows]
| Tool | What it does | Permission |
|---|---|---|
list_workflows | List automation workflows | workflows:read |
get_workflow | One workflow and its steps | workflows:read |
get_workflow_status | One workflow's current state — enabled or not, what triggers it, how many steps it has — with how its runs have gone: the total, and the count now running, waiting, completed, failed and cancelled | workflows:read |
list_workflow_executions | A workflow's runs, one row per contact | workflows:read |
create_workflow | Build a workflow from a spec: a trigger, its settings, and an ordered list of steps. It starts disabled unless you ask otherwise, so you can review it before it runs | workflows:write |
edit_workflow | Change a workflow's name, description, enabled state or trigger, and optionally replace its entire step sequence in the same call | workflows:write |
clone_workflow | Copy a workflow, steps and all, as a new draft. The copy always starts disabled; the original is not modified | workflows:write |
manage_workflow | Pause or resume a workflow. Pausing stops new runs and cancels the ones already in flight, reporting how many it ended | workflows:write |
update_workflow | Edit metadata only: name, description, trigger event, enabled state, re-entry, hourly cap. It cannot author or replace the step graph — edit_workflow is the tool that can | workflows:write |
delete_workflow | Delete a workflow and its execution history. Refused with a 409 while any of its runs are still going | workflows:write |
get_workflow_graph | A workflow's whole graph: every step with its settings, and the transitions between them | workflows:read |
replace_workflow_graph | Replace the whole graph in one call; steps and transitions left out are removed | workflows:write |
add_workflow_step | Add one step, optionally linked after the current last step | workflows:write |
update_workflow_step | Edit one step's name, settings, position or template | workflows:write |
delete_workflow_step | Remove one step | workflows:write |
add_workflow_transition | Connect two steps, optionally on one branch of a condition | workflows:write |
delete_workflow_transition | Remove a connection between two steps | workflows:write |
list_workflow_fields | The contact fields and event properties a condition can test | workflows:read |
list_workflow_versions | A workflow's saved versions | workflows:read |
revert_workflow | Restore a workflow's steps to an earlier version | workflows:write |
list_conversion_goals | The goals a workflow's runs are measured against | workflows:read |
create_conversion_goal | Count a run as converted when the contact records an event in time | workflows:write |
delete_conversion_goal | Remove a conversion goal. Asks the agent to confirm first | workflows:write |
start_workflow_execution | Start a workflow for one contact now | workflows:write |
get_workflow_execution | One run: the steps it took, when, and how it ended | workflows:read |
cancel_workflow_execution | Stop one running execution | workflows:write |
cancel_all_workflow_executions | Stop every running execution of a workflow. Asks the agent to confirm first | workflows:write |
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".
manage_workflow with pause does both. It stops new runs and cancels the runs
already in flight, and it reports how many it cancelled, so the agent can tell "nothing
was running" apart from "I just stopped four hundred journeys". Cancelling is terminal:
resume re-opens the workflow to new runs, it does not put the cancelled contacts back
where they were.
This is the practical edge of the warning on workflows:write: an enabled workflow keeps
sending on its own, long after the conversation that enabled it.
Building a workflow's steps [#building-a-workflows-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. configis typed per step type, across the nine typesTRIGGER,SEND_EMAIL,DELAY,WAIT_FOR_EVENT,CONDITION,EXIT,WEBHOOK,UPDATE_CONTACTandSEND_AT_OPTIMAL_TIME. Because the contract discriminates ontype, a generated SDK narrowsconfigfrom 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_idandto_step_idmust name steps in the same payload, and a step may not point at itself.priorityorders the edges leaving one step, lowest first. ACONDITIONstep'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.
versionmoves 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}/pauseclears 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 [#analytics-and-usage]
| Tool | What it does | Permission |
|---|---|---|
view_analytics | Sent, delivered, opened and bounced counts | analytics:read |
get_usage | This month's and today's send counts against your enforced limits | usage:read |
get_api_usage | The project's API request volume over time. OAuth connections only | usage:read |
list_api_requests | Recent API requests to the project and their status codes. OAuth connections only | usage:read |
list_activity | The activity feed: sends, opens, bounces, workflow steps and more | analytics:read |
get_activity_count | How much activity the project had in the last few minutes | analytics:read |
get_activity_stats | Activity totals by type over a period | analytics:read |
list_upcoming_activity | Scheduled sends and workflow steps that are due soon | analytics:read |
list_top_events | The most frequent events in a period | analytics:read |
list_campaign_analytics | Opens, clicks, bounces and unsubscribes per campaign | analytics:read |
list_top_campaigns | The best-performing campaigns in a period | analytics:read |
Deliverability [#deliverability]
| Tool | What it does | Permission |
|---|---|---|
diagnose_delivery | Why mail from one of your sending domains is not arriving: the domain's DKIM, SPF, DMARC and MX state, the project's recent bounce and complaint counters, and — if you name a recipient — whether that address is suppressed | deliverability:read |
list_deliverability_domains | Delivery outcomes per recipient domain and day, to spot one provider refusing your mail | deliverability:read |
get_dmarc_report | DMARC aggregate reports: who sends as your domains and whether it aligns | deliverability:read |
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 Sendly, so it sits in
Read your data.
Cleaning a list [#cleaning-a-list]
| Tool | What it does | Permission |
|---|---|---|
validate_emails | Check up to 50 addresses in one call | validation:write |
clean_list | Start a background run over every address on a list | validation:write |
get_validation_run | How far a run has got and what it found | validation:read |
list_validation_results | One page of a run's per-address verdicts, filterable by verdict | validation:read |
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 your data.
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 [#subscriber-lists]
| Tool | What it does | Permission |
|---|---|---|
list_lists | The subscriber lists this project keeps, with their sizes | lists:read |
get_list | One list, with its size and its double opt-in setting | lists:read |
create_list | Create an empty list | lists:write |
update_list | Rename a list or change its settings | lists:write |
delete_list | Delete a list and every membership on it | lists:write |
list_list_members | The contacts on a list, filtered by membership status | lists:read |
subscribe_to_list | Subscribe one address to a list; a double opt-in list emails a confirmation first | lists:write |
unsubscribe_from_list | Unsubscribe one address from a list | lists:write |
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 [#topics-and-consent]
| Tool | What it does | Permission |
|---|---|---|
list_topics | The subjects this project mails about, and how many people answered each | topics:read |
get_contact_topic_preferences | Everything one contact has said they want | topics:read |
create_topic | Add a subject people can subscribe to | topics:write |
update_topic | Rename, re-describe, change the default, or retire a topic | topics:write |
set_topic_subscription | Record what one contact wants on one topic | topics:write |
get_topic | One topic and its subscriber count | topics:read |
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 [#events-and-webhooks]
| Tool | What it does | Permission |
|---|---|---|
list_events | The custom events your application has recorded | events:read |
record_event | Record a custom event against an existing contact | events:write |
list_event_names | Every event name the project has recorded | events:read |
get_event_stats | Event counts by name over a period | events:read |
get_event_usage | Which workflows and segments use an event name | events:read |
delete_event_type | Delete an event name and every event recorded under it. Asks the agent to confirm first | events:write |
list_webhooks | List webhook endpoints | webhooks:read |
create_webhook | Add a webhook endpoint | webhooks:write |
update_webhook | Edit a webhook endpoint | webhooks:write |
delete_webhook | Delete a webhook endpoint | webhooks:write |
get_webhook | One webhook endpoint: URL, events and status | webhooks:read |
list_webhook_calls | Recent deliveries to a webhook, with status codes and response times | webhooks:read |
retry_webhook_call | Deliver one webhook call again | webhooks:write |
replay_failed_webhook_calls | Deliver every failed call to a webhook again | webhooks:write |
rotate_webhook_secret | Issue a new signing secret, shown once; the old one stops verifying | webhooks:write |
test_webhook | Send a sample event to a webhook and report how the receiver answered | webhooks:write |
Suppression list [#suppression-list]
| Tool | What it does | Permission |
|---|---|---|
list_suppressions | The addresses Sendly refuses to mail | suppression:read |
add_suppression | Block an address | suppression:write |
remove_suppression | Un-block an address, re-enabling mail to it | suppression:write |
Mailboxes [#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.
| Tool | What it does | Permission |
|---|---|---|
list_mailboxes | The mailboxes on this project's domains, with each one's status and domain | mailboxes:read |
get_mailbox | One mailbox: its email signature, plus the IMAP and SMTP host, port and username for connecting a mail client. The password is not included and cannot be read back | mailboxes:read |
create_mailbox | Create a mailbox on a verified domain | mailboxes:write |
delete_mailbox | Permanently delete a mailbox and every message it holds | mailboxes:write |
compose_mailbox_email | Write an email for a mailbox: draft one from a short brief, rewrite a draft you already have, or suggest subject lines. Returns text and sends nothing — the result always says sent: false | mailboxes:read |
send_mailbox_email | Send a new plain-text or structured branded email from a mailbox's own address, to up to twenty recipients. The recipient can reply, it threads into that mailbox's conversations, and it cannot be recalled. Suppressed recipients and mail the content scanner rejects are refused; a mailbox may send 60 messages an hour this way | mailboxes:send |
list_mailbox_conversations | List and search a mailbox's conversations, with status, spam filtering and cursor pagination | mailbox-conversations:read |
get_mailbox_conversation | Read a thread as text, with attachment metadata; inbound content is untrusted | mailbox-conversations:read |
reply_to_mailbox_conversation | Reply using the latest inbound Reply-To (or From), with plain text or a branded document and preserved threading | mailbox-conversations:reply |
list_inbox_conversations | Conversations across every mailbox in the project, newest first | mailbox-conversations:read |
get_conversation_contact | The Sendly contact behind a conversation, with their recent timeline | mailbox-conversations:read |
get_mailbox_attachment_link | A one-time link you open to download an attachment; the file never reaches the agent | mailbox-conversations:read |
set_conversation_status | Open, snooze or close a conversation, or assign it | mailboxes:write |
mark_conversation_spam | File a conversation as spam, or move it back to the inbox | mailboxes:write |
delete_mailbox_conversation | Permanently delete a conversation and its messages. Asks the agent to confirm first | mailboxes:write |
get_mailbox_project | Which of your projects a mailbox belongs to | mailboxes:read |
list_app_passwords | The app passwords mail clients sign in with; secrets are never shown | mailboxes:read |
create_app_password | Create an app password; you open a one-time link to see it, and the agent never does | mailboxes:write |
revoke_app_password | Revoke an app password; clients using it stop working. Asks the agent to confirm first | mailboxes:write |
update_mailbox_signature | Set, change or remove a mailbox's plain-text email signature, and whether it belongs on new messages and on replies | mailboxes:write |
Five facts about these that are easier to know now than to discover later:
- Reading and replying require explicit grants.
list_mailbox_conversationsandget_mailbox_conversationrequiremailbox-conversations:read;reply_to_mailbox_conversationrequiresmailbox-conversations:reply. Existing grants do not include these permissions.get_mailboxreturns connection settings, while the conversation tools return correspondence. - A mailbox's address cannot be changed after it is created. There is no route and no tool for it — deliberately. To change an address, delete the mailbox and create the one you want. The one thing that can be edited is its signature.
- A send from a mailbox carries its signature unless the agent says none.
update_mailbox_signaturesaves a plain-text signature (at most 1000 characters and 12 lines; no HTML) andget_mailboxshows it. A mailbox has one signature, so there is nothing to choose between.send_mailbox_emailandreply_to_mailbox_conversationtakeincludeSignature: leave it out and Sendly puts the saved signature under the text, above the quoted original on a reply, in both the HTML and the plain-text part; passfalseto send exactly what the body says. The agent should end its body at the last sentence rather than write a sign-off of its own, and may ask you whether you want the signature on a given message. The result says what happened insignatureIncluded. It is not added a second time when a plain body, or a document whose last block is a text block, already ends with the--delimiter and the signature (that last text block may also be the signature alone); a signature pasted any other way is signed again. When the agent confirms the text with you it should say the signature will be added, because it is not among the arguments you approve. The mailbox'sincludeOnNewMessagesandincludeOnRepliesswitches are what its owner chose for the dashboard composer; they do not stop an agent's send, so an agent that should honour them readsget_mailboxand passesfalse. Calling the REST routes directly is unchanged:includeSignaturethere still defaults tofalse. - 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_emailonly needsmailboxes:readbecause it changes nothing: it hands the agent text to show you. Putting that text in someone's inbox as your support address issend_mailbox_emailundermailboxes:send, which is separate fromemails:sendon 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 carries a warning, every call needs the agent's one-time confirmation, and a well-behaved agent shows you the draft and the recipients before confirming.
Deletion is the sharpest tool on this surface: every message the mailbox holds is
erased, Sendly keeps no other copy, and neither the dashboard nor support can bring
it back. Mail sent to the address afterwards is rejected. That is why mailboxes:write
carries a warning, and deleting a mailbox asks the agent to confirm.
API keys [#api-keys]
| Tool | What it does | Permission |
|---|---|---|
list_api_keys | Which keys exist, what each may do, when each was last used. No secret is returned — only the last four characters still exist anywhere | api-keys:read |
get_api_key | One key: its name, what it may do, when it was last used and whether it is revoked. No secret is returned | api-keys:read |
create_api_key | Create a new key, by permission group (tiers) or permission by permission. The secret is not returned to the agent — the result carries a one-time link only you can open | api-keys:write |
rotate_api_key | Replace a key's secret in place, keeping its name and permissions. Same one-time link; the old secret stops working immediately | api-keys:write |
revoke_api_key | Permanently revoke a key. Anything still using it fails on its next request, and it cannot be restored | api-keys:write |
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_keyrequires an explicit list of permissions, and any permission the connection does not itself hold is refused withSCOPE_ESCALATION. The request is rejected outright, never quietly trimmed to fit — so an agent cannot useapi-keys:writeto 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_keysis 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:readchanges nothing, 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.
Billing [#billing]
Sendly bills each project through one metered Stripe subscription, and the mobile Sendly Pro is a subscription the App Store or Google Play sold you.
| Tool | What it does | Permission |
|---|---|---|
billing_status | The project's plan, subscription state and renewal date, spending limits, this month's usage, and your mobile Pro | billing:read |
list_plans | Free, Pay as you go and the mobile Pro, with prices | billing:read |
get_pro_entitlement | Whether your mobile Pro is active, until when, and which store sold it | billing:read |
upgrade_plan | Start pay as you go: a one-time link to a prefilled Stripe Checkout page where you add a card | billing:write |
manage_subscription | cancel at the period end, resume a pending cancel, refund the last paid invoice and end the subscription now, or portal for a one-time link to the Stripe billing portal | billing:write |
get_billing_limits | The project's monthly email cap per stream and how much of each is used. OAuth connections only | billing:read |
update_billing_limits | Set the monthly email cap per stream; sending in a stream stops at its cap. OAuth connections only | billing:write |
list_invoices | The project's invoices with amounts, status and PDF links. OAuth connections only | billing:read |
get_billing_consumption | This billing period's metered usage and the cost so far. OAuth connections only | billing:read |
Every billing change asks the agent to confirm that one call first; opening the portal
does not, because it only hands you a link. extend is always refused: pay as you go bills
only what was sent, so there is no term to lengthen. Mobile Pro is sold and cancelled by
its store, so for a Pro subscriber cancel and portal answer with a link to that
store's subscription page. upgrade_plan, manage_subscription and get_pro_entitlement
act for a person, so a key connection is not offered them.
Account [#account]
Your own account, as the person you signed in as. None of these act on a project, so a key connection, which carries a project and no person, is not offered them.
| Tool | What it does | Permission |
|---|---|---|
get_profile | Your name, email, avatar, billing currency, and whether a deletion is pending | account:read |
update_profile | Change your display name or avatar | account:write |
get_notification_prefs | Whether you get push notifications and the in-app inbox | account:read |
update_notification_prefs | Turn push or the in-app inbox on or off | account:write |
export_data | Start an export of everything the account holds; it runs in the background | account:write |
list_exports | Your recent exports and their status | account:read |
get_export_download_link | A one-time link that downloads a finished export | account:read |
delete_account | Schedule the account for deletion in 30 days | account:write |
set_active_project | Choose the project the dashboard opens on | account:write |
list_brand_logos | Each project's verified domains and sender logos | account:read |
get_referral | Your Refer & Earn link, its clicks, signups and sales, and what you have earned. The first read enrols you in the programme | account:read |
delete_account asks the agent to confirm that one call first, and you type your account
email as part of it. It pauses every project you own, signs you out everywhere and
disconnects every connected app, the one that asked included. Thirty days later the account
and the projects you own are deleted for good. Signing in again before then cancels the
deletion and resumes your projects. Account email such as billing alerts is not a
notification channel, so update_notification_prefs does not change it.
Team [#team]
A project is the team: everyone who belongs to it, each with a role. An agent manages the team only for a project where you are an admin or the owner.
| Tool | What it does | Permission |
|---|---|---|
list_members | The project's members, with each one's email and role | members:read |
invite_member | Add someone who already has a Sendly account, by their email | members:write |
update_member_role | Make a member an admin, or an admin a member | members:write |
remove_member | Remove someone from the project | members:write |
Someone added with invite_member joins at once, so there are no pending invitations to
list or withdraw. An email with no Sendly account is refused: the person signs up first,
then the agent adds them. remove_member asks the agent to confirm that one call first,
and nobody can remove themselves. To start or delete a team, create or delete a project.
Support [#support]
| Tool | What it does | Permission |
|---|---|---|
create_support_ticket | Write to Sendly's support team, with optional https links to screenshots | support:write |
list_support_tickets | The tickets you opened, newest first | support:read |
create_appeal | Ask a person to review a project's sending suspension | support:write |
list_appeals | A project's appeals and when each answer is due | support:read |
A ticket reaches the same support inbox as the support form, and the reply comes to your account email. A key connection has no account email, so it asks for no reply. An appeal is only for a suspended project, one per project per day.
Connections [#connections]
What a project or your account is connected to: the project's Slack channel, the domains whose DNS DoDomain manages, and the AI apps connected to your Sendly account.
| Tool | What it does | Permission |
|---|---|---|
list_connections | Everything the project is connected to, and your connected AI apps | connections:read |
get_connect_links | A one-time link that connects Slack, or lets DoDomain set up one domain's DNS | connections:write |
disconnect | Disconnect Slack from the project | connections:write |
reverify | Ask DoDomain to re-check a domain's DNS now | domains:write |
get_slack_connection | The Slack workspace, channel and notice kinds | connections:read |
update_slack_notifications | Choose which notices post to Slack | connections:write |
list_connected_apps | The AI apps connected to your account and what each may do | connections:read |
revoke_connected_app | Disconnect an AI app from your account | connections:write |
narrow_connected_app | Take permissions away from a connected AI app | connections:write |
Connecting always happens in your browser, on Slack's or DoDomain's own page, so
get_connect_links answers a /go/ link rather than a result. Changing or removing the
Slack connection needs a project admin. disconnect and revoke_connected_app ask the
agent to confirm that one call first. The Slack and connected-app tools act for a person,
so a key connection cannot use them.
Tools that hand you a link [#tools-that-hand-you-a-link]
Eight tools cannot finish inside the agent, and answer with
status: "action_required" and a URL for you to open instead of a result:
| Tool | What the link does | How long it lasts |
|---|---|---|
create_api_key | Shows the new key's secret, once | 5 minutes |
rotate_api_key | Shows the rotated key's new secret, once | 5 minutes |
start_domain_setup | Guided DNS setup at your registrar, then returns you to Sendly | Short-lived, set by the session |
upgrade_plan | Opens Stripe Checkout, prefilled, to add a card | 15 minutes, once |
manage_subscription | With portal, opens your Stripe billing portal | 15 minutes, once |
get_export_download_link | Downloads a finished data export | 15 minutes, once |
get_connect_links | Connects Slack, or starts DoDomain's DNS setup for one domain | 15 minutes, once |
request_scopes | Approves more permissions for this app, or opens the key form with them ticked | 15 minutes, once |
A billing, export or connect link is a /go/ link: it works once, for 15 minutes, and only when the account
it was issued to is signed in. What it opens is created only when you open it, so a
link copied out of a transcript is worth nothing to anyone else.
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.
Confirmations [#confirmations]
Anything that cannot be undone (sending, deleting, cancelling or refunding, removing a
member, disconnecting) first answers CONFIRMATION_REQUIRED with next.args.confirmToken.
The agent tells you exactly what will happen; if you agree, it calls the same tool again
with those arguments. A token works once, for 10 minutes, for exactly that call: changing
any argument, or calling a different tool with it, is refused with a fresh token.
Every refusal carries a code, and most carry a next naming the tool that repairs it:
request_scopes for a missing permission, upgrade_plan for an exhausted plan, the same
tool with the confirm token for a confirmation. The troubleshooting table
lists every code. The agent brief at
docs.sendly.now/agent-setup/prompt.md
says the same to an agent, with every tool grouped by the permission it needs.
Permissions and consent [#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:
| Permission | Consent-screen wording | Carries a warning |
|---|---|---|
emails:send | Send emails from your verified domains | Yes |
emails:read | View the emails you have sent and their delivery status | No |
contacts:read | View your contacts and their custom fields | No |
contacts:write | Create, update, and delete your contacts | No |
campaigns:read | View your campaigns and their performance | No |
campaigns:write | Create, edit, and organize your campaigns | No |
segments:read | View your segments and who belongs to them | No |
segments:write | Create, edit, and delete your segments | No |
workflows:read | View your automation workflows and their runs | No |
workflows:write | Create, edit, enable, and delete your automation workflows | Yes |
templates:read | View your email templates | No |
templates:write | Create, edit, and delete your email templates | No |
domains:read | View your sending domains and their verification status | No |
domains:write | Add and remove sending domains, and trigger verification | No |
webhooks:read | View your webhook endpoints and their delivery history | No |
webhooks:write | Create, edit, and delete your webhook endpoints | No |
suppression:read | View the addresses on your suppression list | No |
suppression:write | Add and remove addresses on your suppression list | Yes |
analytics:read | View your sending analytics and engagement metrics | No |
usage:read | View your usage totals and billing limits | No |
events:read | View the custom events your application has recorded | No |
events:write | Record custom events for your contacts | No |
projects:read | View your projects and their settings | No |
projects:write | Create, change, reset and delete projects on your account | Yes |
api-keys:read | See which API keys exist, including what each one is allowed to do | Yes |
api-keys:write | Create, rotate, and revoke API keys — these keep working even after you disconnect this app | Yes |
campaigns:send | Send or schedule your campaigns to their audience | Yes |
mailboxes:read | View the mailboxes on your domains and their settings | No |
mailboxes:write | Create and delete mailboxes on your verified domains | Yes |
emails:test | Send test emails to your own address from the Sendly sandbox | No |
deliverability:read | Check why mail from one of your domains is not arriving | No |
mailboxes:send | Write and send new email from your hosted mailboxes, as that address | Yes |
validation:read | View your email validation runs and their results | No |
validation:write | Check whether email addresses can receive mail — this is billed per address | No |
topics:read | View the topics you mail about and who is subscribed to each | No |
topics:write | Create and edit topics, and change what your contacts are subscribed to — this decides who your campaigns reach | No |
lists:read | View your subscriber lists and who is on them | No |
lists:write | Create, rename, and delete your subscriber lists | No |
mailbox-conversations:read | Read the conversations in your hosted mailboxes — every message and attachment people have sent you | Yes |
mailbox-conversations:reply | Reply to conversations in your hosted mailboxes, from the mailbox's own address | Yes |
billing:read | See your plan, usage, invoices and spending limits | No |
billing:write | Start a checkout, change spending limits, open the billing portal, cancel or refund | Yes |
account:read | See your profile and notification preferences | No |
account:write | Edit your profile and preferences, export your data, delete your account | Yes |
members:read | See who belongs to your projects | No |
members:write | Add and remove project members and change their roles | Yes |
connections:read | See connected services such as Slack and connected AI apps | No |
connections:write | Connect, re-verify and disconnect services | Yes |
support:read | See your support tickets | No |
support:write | Open support tickets and suspension appeals | No |
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. lists:read and lists:write govern the /api/v1/lists endpoints and the
five list tools that sit on top of them (list_lists, get_list, create_list,
update_list and delete_list). No agent tool adds people to a list.
mailbox-conversations:read and mailbox-conversations:reply govern the mailbox
conversation endpoints of the REST API (list a mailbox's conversations, read a
conversation's messages and attachments, and reply to a conversation).
Granting mailbox-conversations:read unlocks list_mailbox_conversations and
get_mailbox_conversation; granting mailbox-conversations:reply unlocks
reply_to_mailbox_conversation.
Choosing a project [#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 withPROJECT_REQUIREDand told to calllist_projectsfirst. Well-behaved agents do this on their own. AprojectIdthat is not one of your projects gets the samePROJECT_REQUIREDbefore 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 [#changing-your-mind]
To withdraw one permission, go to Settings → Connected apps and untick it. The connection stays; the agent keeps everything else.
To give an agent more, it calls request_scopes and hands you a one-time link. For an
app, the link opens a page where you approve the extra permissions; then reconnect Sendly in
the app, and it will not ask again. For a key connection, the link opens the key form with
those permissions ticked, and you give the agent the new key. Nothing is granted until you act.
To end the connection entirely, choose Disconnect on the same page. For a key connection, revoke the key in Settings → API keys instead.
Every tool call re-checks your live grant before it runs, so a withdrawn permission starts being refused **at once** — even though the agent's access token has not expired — and disconnecting stops the agent entirely on its very next call.The tool list catches up shortly after. An agent's listing is built from the token it
is holding, so a withdrawn tool can still appear there until that token is replaced:
every call of it is refused with SCOPE_MISSING in the meantime, so no authority
survives the change. The token mint reads the same live grant the gate does, which
means the withdrawn tool disappears from the listing as soon as the agent refreshes its
token, and immediately if it reconnects. Access tokens last 30 days by default, so the
listing can lag for that long; the refusal does not.
A refresh presented after a full disconnect is refused outright rather than honoured.
Troubleshooting [#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.
| What you see | What it means | Fix |
|---|---|---|
401 from the endpoint | No valid credential was presented | Run the OAuth flow, or put a valid sk_… key on the Authorization header. A pk_… key or a browser session will not be accepted |
SCOPE_MISSING | This connection was never granted that permission, or it was withdrawn | The denial's next names request_scopes with the permission it needs. The agent calls it and you approve the extra permission |
CONSENT_REVOKED | The connection was disconnected from your Sendly account | Reconnect the app from Settings → Connected apps |
KEY_REVOKED | The API key this connection uses was revoked or rotated | Reconnect with a current key from Settings → API keys |
PROJECT_REQUIRED | Your account has more than one project (or none), so the target is ambiguous — or the projectId passed is not one of your projects | Have the agent call list_projects and pass the chosen id as projectId |
PROJECT_FIXED | An API-key connection was given a projectId, but a key is bound to one project | Drop the argument, or use a key belonging to the other project |
USER_DECLINED | Your client asked you to confirm an irreversible action and you said no. Nothing was done — the refusal happens before Sendly is called at all | Nothing to fix. Tell the agent what you would like instead |
CONFIRMATION_REQUIRED | A tool that cannot be undone was called without a valid confirm token for exactly that call. Nothing was done | Have the agent tell you what the call will do, then call again with the denial's next.args, which carry a fresh token |
INVALID_ARGUMENTS | The arguments cannot produce a call — a tool's own cross-field rule refused them, for example send_email given a fromName with no from. Nothing was done | The message says what to change. Do not retry the same arguments: they produce the same refusal |
SCOPE_ESCALATION | create_api_key asked for a permission this connection does not itself hold | Ask for a key whose permissions are a subset of what you granted the agent, or create the key yourself in Settings → API keys |
TOOL_EXECUTION_FAILED | The call reached Sendly but could not be completed. upstreamStatus: 429 means the connection hit its rate limit | Follow the denial's next: upgrade_plan when the plan has no sends left, the same tool when a retry can help, after retryAfterSeconds when the refusal carries it. With no next, retrying will not help. If it persists, contact support@sendly.now |
The destructive annotation Sendly publishes marks a narrower thing, and it is worth
knowing which: a tool that erases or overwrites something that was already there —
delete_contact, edit_workflow (whose steps replace every existing step),
revoke_api_key (which invalidates a live secret), delete_list (which takes the
memberships with it). A send is not marked destructive, because it destroys
nothing; it is irreversible in the other direction, and no annotation captures that.
Do not read an unmarked tool as a safe one.
Sendly can additionally ask through the protocol, and USER_DECLINED is the
answer a decline produces, but only clients on a transport that carries a
session-scoped conversation will ever show it; on today's endpoint that request cannot
be delivered, so no prompt of Sendly's own appears. Nothing depends on it: the
permission you ticked on the consent screen is the grant, and every interactive tool
is complete by returning a link.
The confirmation Sendly enforces itself is the confirm token: every tool that cannot be undone answers its first call with a single-use token, and only a second call carrying it runs. That one works on this transport precisely because it asks for an argument rather than for a conversation.
How it relates to the rest of the platform [#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.
Read, reply, and branded mailbox messages [#read-reply-and-branded-mailbox-messages]
Grant mailbox-conversations:read explicitly to use list_mailbox_conversations
and get_mailbox_conversation. Reading does not mark messages as read. These tools
return message text and attachment metadata, not downloaded attachment contents.
Grant mailbox-conversations:reply separately to answer the latest inbound Reply-To (or From)
with reply_to_mailbox_conversation. Neither permission is held by a key or connection
created before they existed; those need a new grant before the tools appear.
send_mailbox_email starts a new conversation under mailboxes:send. Both send
and reply accept either body (plain text) or document (structured rich content),
never both. Documents are rendered by React Email into HTML and a matching plain-text
alternative. Branding can be reused by passing the same brand object to each message.
{
"mailboxId": "<mailbox-id>",
"to": ["recipient@example.com"],
"subject": "Your project update",
"document": {
"preview": "The latest from your team",
"brand": {
"name": "Acme",
"logoUrl": "https://example.com/logo.png",
"accentColor": "#2458d3",
"backgroundColor": "#f2f4f8"
},
"blocks": [
{ "type": "heading", "text": "Your project is ready" },
{ "type": "text", "text": "Here is what changed this week." },
{ "type": "image", "src": "https://example.com/demo.gif", "alt": "Product demonstration" },
{ "type": "button", "text": "Open your project", "href": "https://example.com/project" }
],
"footer": "Acme customer success"
}
}
Use columns with two or three arrays of blocks for feature cards and comparisons;
columns stack on phones. divider adds a horizontal rule. Brand tokens support six-digit
hex colors and sans/serif/mono fonts. Images and GIFs need public HTTPS URLs; Sendly does
not upload files or accept arbitrary JSX, HTML or CSS. Mail clients can block remote
images or show an animation's first frame, so supply descriptive alt text.
Send and reply share a 60-message hourly mailbox budget and screen authored content before submission. A reply quotes the original as escaped text rather than forwarding its markup. The mailbox sets the sender; a reply derives its recipient from the thread.