# Sendly Documentation — full text > Every Sendly documentation page, in sidebar order, as one Markdown document. > Sendly is an email platform for developers, built on AWS SES for transactional > email, marketing campaigns, and visual automation workflows. > > The link index is at https://docs.sendly.now/llms.txt, and any single page is served as > Markdown at https://docs.sendly.now/llms.mdx/. > > NOT INCLUDED: the generated API-reference pages. Each one renders the OpenAPI > document rather than carrying prose, so inlining them would add a hundred empty > sections. Read the contract itself at https://docs.sendly.now/openapi.json — it is the same > content in a form built to be parsed. ## MCP tools by permission Agent brief: https://docs.sendly.now/agent-setup/prompt.md - Read your data: billing_status, check_domain, compose_mailbox_email, diagnose_delivery, export_contacts, get_activity_count, get_activity_stats, get_api_key, get_api_usage, get_audit_log, get_billing_consumption, get_billing_limits, get_campaign, get_campaign_stats, get_contact, get_contact_field_usage, get_contact_topic_preferences, get_conversation_contact, get_dmarc_report, get_domain, get_domain_connect_status, get_domain_logo, get_domain_logo_readiness, get_domain_warmup, get_email, get_event_stats, get_event_usage, get_export_download_link, get_list, get_mailbox, get_mailbox_attachment_link, get_mailbox_conversation, get_mailbox_project, get_notification_prefs, get_org_inbox_counts, get_org_overview, get_pro_entitlement, get_profile, get_project, get_project_security, get_project_setup_state, get_referral, get_segment, get_slack_connection, get_snippet, get_suppression, get_template, get_template_usage, get_topic, get_usage, get_validation_run, get_webhook, get_workflow, get_workflow_execution, get_workflow_graph, get_workflow_status, list_activity, list_api_keys, list_api_requests, list_app_passwords, list_appeals, list_brand_logos, list_campaign_analytics, list_campaign_failures, list_campaigns, list_connected_apps, list_connections, list_contact_events, list_contact_field_values, list_contact_fields, list_contacts, list_conversion_goals, list_deliverability_domains, list_emails, list_event_names, list_events, list_exports, list_inbox_conversations, list_invoices, list_list_members, list_lists, list_mailbox_conversations, list_mailboxes, list_members, list_org_inbox_conversations, list_org_inbox_mailboxes, list_org_mailboxes, list_orgs, list_plans, list_segment_contacts, list_segments, list_snippets, list_support_tickets, list_suppressions, list_template_versions, list_templates, list_top_campaigns, list_top_events, list_topics, list_upcoming_activity, list_validation_results, list_webhook_calls, list_webhooks, list_workflow_executions, list_workflow_fields, list_workflow_versions, list_workflows, lookup_contacts, view_analytics - Create and edit: add_domain, add_segment_members, add_suppression, add_workflow_step, add_workflow_transition, bulk_create_contacts, bulk_set_subscription, cancel_workflow_execution, clean_list, clone_workflow, compute_segment, create_app_password, create_campaign, create_contact, create_conversion_goal, create_list, create_mailbox, create_project, create_segment, create_snippet, create_template, create_topic, create_webhook, create_workflow, delete_domain_logo, delete_workflow_step, delete_workflow_transition, duplicate_campaign, duplicate_template, edit_workflow, import_contacts, manage_campaign, manage_domain_warmup, manage_workflow, mark_conversation_spam, record_event, refresh_org, refresh_segment, remove_segment_members, replace_workflow_graph, replay_failed_webhook_calls, retry_failed_campaign_sends, retry_webhook_call, reverify, revert_template, revert_workflow, rotate_webhook_secret, send_campaign_test, send_test_email, set_conversation_status, set_topic_subscription, start_domain_setup, start_workflow_execution, subscribe_to_list, test_webhook, unsubscribe_from_list, update_campaign, update_contact, update_domain_stream, update_list, update_mailbox_signature, update_project, update_segment, update_snippet, update_template, update_topic, update_webhook, update_workflow, update_workflow_step, upload_domain_logo, upload_image, upsert_contact, validate_emails, verify_domain - Delete, publish or send: bulk_delete_contacts, bulk_purge_contacts, cancel_all_workflow_executions, cancel_scheduled_email, delete_campaign, delete_contact, delete_contact_field, delete_conversion_goal, delete_domain, delete_event_type, delete_list, delete_mailbox, delete_mailbox_conversation, delete_project, delete_segment, delete_snippet, delete_template, delete_webhook, delete_workflow, purge_contact, remove_suppression, reply_to_mailbox_conversation, reschedule_email, reset_project, revoke_app_password, send_batch_emails, send_campaign, send_email, send_mailbox_email - Billing and subscription: manage_subscription, update_billing_limits, upgrade_plan - Profile, preferences, account deletion: delete_account, export_data, set_active_project, update_notification_prefs, update_profile - Members and invites: invite_member, remove_member, update_member_role - Connected services: disconnect, get_connect_links, narrow_connected_app, revoke_connected_app, update_slack_notifications - Support tickets: create_appeal, create_support_ticket - API keys: create_api_key, revoke_api_key, rotate_api_key --- # Sendly email API and SDK documentation (/) ## Send your first email in a minute [#send-your-first-email-in-a-minute] **No account yet?** [Start keyless](/keyless-start): one call with your email address, a 6-digit code from your inbox, and you can send **20 free test emails** to yourself. No signup, no API key from a dashboard, no domain and no card. Claim the test project into a free account later. With an account, every new project gets the same **20 free test emails** from its sandbox address to your own inbox. Click **Send me a test email** on the dashboard, ask your agent to call `send_test_email`, or send one with an API key: ```bash curl -X POST https://api.sendly.now/api/v1/emails/test \ -H "Authorization: Bearer sk_your_api_key" \ -H "Content-Type: application/json" \ -d '{"subject": "Hello from Sendly", "body": "

It works.

"}' ``` The response's `test_allowance` says how many are left. When they run out, [verify a domain](/guides/verifying-domains): a verified domain sends to anyone on the free plan, no card needed. ## What is Sendly? [#what-is-sendly] Sendly is an email platform for developers, built on top of AWS SES. It handles transactional sends, marketing campaigns, and automation workflows against the same contact database, and is designed to scale to millions of contacts. ## Key Features [#key-features] Already on Resend, SendGrid, Postmark, Mailgun, or Plunk? Keep your existing vendor SDK — swap the base URL and API key Send transactional emails via API with template support and variable substitution Create and send one-time email broadcasts to your contacts with advanced scheduling Build automated email sequences with visual workflow builder and conditional logic Manage millions of contacts with custom fields and CSV import capabilities Create dynamic audience segments based on contact data and behavior Create reusable email templates for transactional and marketing emails Track events and use them to trigger workflows and segment audiences Understand Sendly's billing model and pricing Connect Claude or any MCP client so an agent can work in your Sendly account, with the permissions you choose One prompt an AI coding agent can fetch and run to connect itself to Sendly — Claude Code, Codex, Cursor, and more ## Quick Links [#quick-links] Explore the complete API documentation Deploy Sendly on your own infrastructure Learn how to verify your domains for sending emails Let Sendly publish your DNS records for you and watch them for drift Manage your API keys and authentication Plain definitions of the email terms that show up in Sendly, in an API error, or in a conversation about why a message did not arrive Answers to the questions Sendly actually gets, about agents, pricing and SDKs ## Open Source [#open-source] The official Sendly SDKs are open source on GitHub — [sendly-js](https://github.com/DevinoSolutions/sendly-js) and [sendly-python](https://github.com/DevinoSolutions/sendly-python). Issues and contributions are welcome. ## Support [#support] If you need help or have questions: - Read the documentation - Open an issue on the [SDK repositories](https://github.com/DevinoSolutions) - Email [support@sendly.now](mailto:support@sendly.now) - Join the [Sendly Discord](https://discord.gg/RQUKvXZtEH) to ask the team and other developers --- # Send a test email with no account (/keyless-start) You can try Sendly before you make an account. One call with your email address starts a **keyless test project**: Sendly emails you a 6-digit code, and once you confirm it you can send **20 free test emails** to that inbox. No signup, no domain, no DNS and no card. When you want more, claim the project into a free account and everything you sent comes with it. This page is written for both people and coding agents. An agent can run every step itself; the only thing it needs from you is the code from your inbox. ## 1. Start [#1-start] ```bash curl -X POST https://api.sendly.now/api/v1/keyless/start \ -H "Content-Type: application/json" \ -d '{ "email": "you@yourcompany.com" }' ``` Starting a keyless project costs a small proof of work, so the first call answers `428` with a challenge: ```json { "status": 428, "code": "proof_required", "details": { "reason": "proof_missing", "challenge": "AQAUAAABmp…", "algorithm": "sha256", "difficultyBits": 20, "expiresAt": "2026-11-17T09:05:00.000Z", "header": "Sendly-Keyless-Proof", "howTo": { "node": "node -e \"…\"", "python": "python3 -c \"…\"", "pythonWindows": "py -c \"…\"" }, "signUpUrl": "https://app.sendly.now/auth/signup" } } ``` Find a decimal nonce (at most 32 digits) such that SHA-256 over the UTF-8 bytes of `:` starts with `difficultyBits` zero bits. `details.howTo.node` and `details.howTo.python` are ready-to-run one-liners with your challenge filled in; each prints the full header value. On Windows use `details.howTo.pythonWindows` (the `py` launcher), since stock Windows has no `python3`. At the usual 20 bits that takes 1 to 3 seconds. The same solver, standalone: ```bash # CHALLENGE and BITS come from details.challenge and details.difficultyBits. PROOF=$(node -e "const c=process.argv[1],d=+process.argv[2],k=require('crypto'),h=(s)=>k.createHash('sha256').update(s).digest('hex');for(let n=0;;n++)if(parseInt(h(c+':'+n).slice(0,8),16)>>>(32-d)===0){process.stdout.write(c+':'+n);break}" "$CHALLENGE" "$BITS") ``` Send the same request again with the proof: ```bash curl -X POST https://api.sendly.now/api/v1/keyless/start \ -H "Content-Type: application/json" \ -H "Sendly-Keyless-Proof: $PROOF" \ -d '{ "email": "you@yourcompany.com" }' ``` ```json { "key": "pk_test_…", "project_id": "5f0c…", "email": "you@yourcompany.com", "verified": false, "code_expires_at": "2026-11-17T09:20:00.000Z", "test_allowance": { "limit": 20, "used": 0, "remaining": 20 }, "claim_url": "https://app.sendly.now/claim/keyless#pk_test_…", "next": { "call": "POST /api/v1/keyless/verify", "say": "I sent a 6-digit code to you@yourcompany.com. Tell me the code… check your Spam folder." } } ``` **Keep the key.** It is shown once. It is a test key: it can only send test emails to the address you confirm, and every other endpoint refuses it. Each challenge works once and for 5 minutes. You are only asked for a proof when the call would otherwise succeed: a bad email or a spent limit answers its own error first. ## 2. Confirm your email [#2-confirm-your-email] Sendly sends a 6-digit code to the address you gave. Paste it back (an agent asks you for it): ```bash curl -X POST https://api.sendly.now/api/v1/keyless/verify \ -H "Authorization: Bearer pk_test_…" \ -H "Content-Type: application/json" \ -d '{ "code": "123456" }' ``` A code lasts 15 minutes and allows 5 tries. No email? Check your Spam folder first, then `GET /api/v1/keyless` with the same key: its `code_email.status` says whether the code email is `queued`, `sent`, `delivered`, `bounced`, `unconfirmed` (our mail provider never answered, so it may still arrive) or `not_sent`, and `code_email.say` is a sentence for your user. `POST /api/v1/keyless/resend` sends a new code (up to 3 codes, a minute apart); a code whose email Sendly could not send (`not_sent`) does not count against the 3, up to 5 such resends. A resend Sendly cannot send at all answers `503` and does not count either. The reply's `next.say` tells your user how many test emails are left. ## 3. Send your test emails [#3-send-your-test-emails] ```bash curl -X POST https://api.sendly.now/api/v1/emails/test \ -H "Authorization: Bearer pk_test_…" \ -H "Content-Type: application/json" \ -d '{ "subject": "Hello from Sendly", "body": "

It works.

" }' ``` The email comes from your project's sandbox address (`test-…@sendly.now`) and can only reach the address you confirmed. A first email from a new sender can land in Spam: if it is not in the inbox within a minute, look there. The response's `test_allowance` counts down from 20. `GET /api/v1/keyless` with the same key shows where you stand. ## 4. Claim it when you want more [#4-claim-it-when-you-want-more] Open `claim_url` and sign up for free (or sign in). If you sign up with an email and password, the confirmation link can open in a new tab: the claim page there carries on, and so does the first tab once your address is confirmed. The `pk_test_` key stops working once the project is claimed: use your account's API keys from then on. The test project moves into your account with everything it sent, and you can add your own domain, which sends to anyone. The free plan needs no card; see [pricing](https://sendly.now/pricing). The 20 test emails are per project, so claiming does not reset them. ## Limits [#limits] - 20 test emails per keyless project, only to the confirmed address. - Keyless projects are for testing: an unconfirmed one is deleted after 24 hours, an unclaimed one after 30 days. Claim it to keep it. - One inbox can start 3 keyless projects a day (plus-aliases like `you+1@` count as that inbox), and one network (an IPv4 /24 or IPv6 /48) 5 a day. These counts reset at 00:00 UTC: a `429` says so in its `detail`, and `details.resetsAt` is the exact time. A start whose code email Sendly could not send (`code_email.status` is `not_sent` because of a problem on our side) does not count: the next start from that inbox or network gives its place back. A start answered `503` because the code could not be sent at all does not count either. - An agent that cannot run code can skip the proof of work with a free account instead (`details.signUpUrl`), or connect over [MCP](/guides/mcp) and call `send_test_email`. --- # FAQ (/faq) These are the same answers given on [sendly.now/agents](https://sendly.now/agents) and [sendly.now/pricing](https://sendly.now/pricing), plus the failure codes from the [MCP guide](/guides/mcp#troubleshooting), collected in one page. Only if you leave that permission on. `emails:send` sits in the consent screen's "Delete, publish or send" row with a sentence saying that mail sent this way reaches real inboxes and cannot be recalled, and every send asks the agent to confirm it once. Untick it and the send tools are never registered, so the agent does not see them at all. `https://app.sendly.now/api/mcp`, over Streamable HTTP. It accepts either an OAuth 2.1 access token obtained with PKCE, or a Sendly secret key on the `Authorization` header. Sending-only keys and dashboard sessions are refused. No. Dynamic client registration is open, and the protected-resource and authorization-server metadata are published at their conventional well-known URLs, so a client that has never talked to Sendly can discover what it needs and start the flow on its own. See [Onboard your agent](/agent-setup) for the exact command per client. An OAuth connection is revoked in **Settings → Connected apps**. A key connection is revoked by revoking the key in **Settings → API keys**, which stops the agent on its next call. A key connection deliberately does not appear in Connected apps, because there is no consent row behind it. An OAuth connection can, choosing the project per call. A secret key cannot: it is bound to its own project, and a project id that disagrees is refused with `PROJECT_FIXED` rather than quietly ignored. A Markdown file written for an AI coding agent to fetch and run directly, not for a person to read. It walks the agent through getting credentials, connecting over MCP or the SDK, verifying the connection, and reporting back to you. The [Onboard your agent](/agent-setup) pages show the same commands for a person reading in a browser. No. There is no monthly fee, no per-seat fee and no per-contact fee. You pay $1.00 per 1,000 emails you actually send, and less than that as your volume grows. 5,000 emails per calendar month, shared across transactional sends, campaigns, workflows and inbound mail. No card is required, and the full REST API, SDKs and webhooks are included. Yes. Every new project gets 20 free test emails from its sandbox address to your own inbox, with no domain, no DNS and no card: the dashboard's **Send me a test email** button, `POST /api/v1/emails/test`, or the `send_test_email` tool for an agent. When they run out, [verify a domain](/guides/verifying-domains); it sends to anyone on the free plan. `sendly-sdk` on npm and `sendly-python` on PyPI, both reading the `SENDLY_API_KEY` environment variable by default. Create a key at [Settings → API keys](https://app.sendly.now/settings/api-keys). Both SDKs are generated from the same OpenAPI contract as the [API reference](/api-reference/overview) and are open source — [sendly-js](https://github.com/DevinoSolutions/sendly-js) and [sendly-python](https://github.com/DevinoSolutions/sendly-python). `401` means no valid credential was presented: run the OAuth flow, or put a valid `sk_…` key on the `Authorization` header. `SCOPE_MISSING` means this connection was never granted that permission, or a key predates per-capability permissions — re-approve it in **Settings → Connected apps**, or create a new key with the permissions ticked. The full table of failure codes is in the [MCP guide's troubleshooting section](/guides/mcp#troubleshooting). Have a question that is not here? Email [support@sendly.now](mailto:support@sendly.now). --- # SDKs (/sdks) Sendly maintains official client libraries so you can call the API from your own code without hand-writing HTTP requests. Both SDKs are hand-written for their language and contract-tested against the same OpenAPI specification that powers the [API Reference](/api-reference/overview) on this site — a test suite in each repo fails if a spec operation is neither implemented nor explicitly recorded as one an API key cannot call, and if any SDK method targets an endpoint the spec does not declare — so the methods and types you use always match what the live API accepts and returns. Official TypeScript / JavaScript SDK. Type-safe access to every endpoint an API key can call — emails, contacts, campaigns, segments, workflows, analytics, mailboxes, and more. Official Python SDK with full type hints. The same resources, with a Pythonic API. Already sending through Resend, SendGrid, Postmark, Mailgun, or Plunk? You don't need either SDK to try Sendly — the API speaks those providers' transactional-send dialects, so you can keep your existing vendor SDK and swap the base URL and API key. See [Migrate from another provider](/migrate). Both SDK repositories are open source and welcome issues and pull requests. ## TypeScript / JavaScript [#typescript--javascript] Install from npm: ```bash npm install sendly-sdk ``` Or install the latest `main` directly from GitHub: ```bash npm install github:DevinoSolutions/sendly-js ``` Create a client with your secret API key and send an email: ```ts import { Sendly } from "sendly-sdk"; const sendly = new Sendly({ apiKey: process.env.SENDLY_API_KEY! }); const receipt = await sendly.emails.send({ from: "hello@your-domain.com", to: "user@example.com", subject: "Welcome to Acme", body: "

Glad to have you.

", }); console.log(receipt.id, receipt.status); // a real delivery state — poll emails.get(id) ``` ## Python [#python] Requires Python 3.10 or newer. Install from PyPI (the distribution is `sendly-python`; the import name is `sendly`): ```bash pip install sendly-python ``` Or install the latest `main` directly from GitHub: ```bash pip install git+https://github.com/DevinoSolutions/sendly-python.git ``` The client reads your API key from the `SENDLY_API_KEY` environment variable: ```python from sendly import Sendly sendly = Sendly() # reads SENDLY_API_KEY receipt = sendly.emails.send( { "from": "hello@yourdomain.com", "to": "customer@example.com", "subject": "Welcome aboard", "body": "

Thanks for signing up!

", } ) # `status` is a real delivery state; poll `emails.get(receipt["id"])` for the # events behind it. print(receipt["id"], receipt["status"]) ``` You can also pass the key explicitly with `Sendly(api_key="sk_...")`. ## The `/api/v1` surface [#the-apiv1-surface] From `sendly-sdk` **0.3.0** and `sendly-python` **0.2.0**, both SDKs also cover the versioned `/api/v1` surface: **campaigns**, **segments**, **workflows**, **analytics**, **usage**, and the v1 event methods — since joined by the **test send** and the **project read** described below, and, from **1.0.0**, the default **email send** itself. The same client object serves both surfaces — no separate setup. ```ts // Create a campaign, then send it — both calls accept an idempotency key, // so a retried request can never create or send the campaign twice. const campaign = await sendly.campaigns.create( { name: "October launch", subject: "We shipped something big", body: "

It's here

", from: "news@your-domain.com", audience_type: "ALL", }, { idempotencyKey: "launch-oct-2026" }, ); await sendly.campaigns.send(campaign.id, undefined, { idempotencyKey: "launch-oct-2026-send" }); ``` ```python # The same two calls in Python. campaign = sendly.campaigns.create( { "name": "October launch", "subject": "We shipped something big", "body": "

It's here

", "from": "news@your-domain.com", "audience_type": "ALL", }, idempotency_key="launch-oct-2026", ) sendly.campaigns.send(campaign["id"], idempotency_key="launch-oct-2026-send") ``` ### Pagination that walks itself [#pagination-that-walks-itself] Every v1 list endpoint returns a cursor page — `{ data, has_more, next_cursor }` — and every list method has a companion iterator that follows the cursor for you (`listAll` in TypeScript, `iter_list` in Python): ```ts for await (const contact of sendly.segments.listContactsAll("seg_123")) { console.log(contact.email); } ``` ```python for campaign in sendly.campaigns.iter_list({"limit": 100}): print(campaign["name"], campaign["status"]) ``` Keep the filters identical for the whole walk — the cursor encodes them, and changing them mid-pagination returns a `422 validation_error` telling you to restart from the first page. ### Typed errors on both dialects [#typed-errors-on-both-dialects] Legacy `/api/*` endpoints report failures as a `{ success, error }` envelope; `/api/v1/*` endpoints answer with [RFC 9457 problem documents](/api-reference/errors). Both land on the same exception classes, so one `catch` handles either surface. On a v1 failure two extra fields are populated: `requestId` (`request_id` in Python) — quote it in support requests — and `fieldErrors` (`field_errors`), the per-field breakdown of a `422 validation_error`. ### Verifying webhooks [#verifying-webhooks] Both SDKs ship a webhook signature verifier (`verifySignature` / `verify_signature`) that checks the `X-Sendly-Signature` and `X-Sendly-Timestamp` headers against the raw request body with a constant-time comparison. See [Webhooks](/guides/webhooks) for the delivery contract. ### Sending on `/api/v1` [#sending-on-apiv1] From `sendly-sdk` **1.0.0** and `sendly-python` **1.0.0**, `emails.send` **is** the versioned send. It posts to `POST /api/v1/emails` and answers `202` with `{ id, status, to, from }`, where `status` is a real delivery state you can poll on. It takes a single recipient — use `cc`/`bcc` to copy others — instead of fanning an array out. The pre-1.0 send is kept, unchanged, as `emails.sendLegacy` (`send_legacy` in Python): it posts to the legacy `POST /api/emails`, fans an array `to` out to several recipients, and answers `{ emails, timestamp }` with row ids and **no delivery status**. Upgrading from 0.x is either a rename to `sendLegacy` (old shapes kept) or reading the receipt instead of the envelope; each repository's README has the details. ```ts const receipt = await sendly.emails.send( { to: "user@example.com", subject: "Order confirmed", body: "

Thanks.

" }, { idempotencyKey: `order-${orderId}` }, ); console.log(receipt.status); ``` ### Test sends [#test-sends] `emails.sendTest` (`send_test`) exercises rendering and the whole send path without reaching a live recipient. Two details are easy to get backwards: - **The sandbox address is the _sender_, not the destination.** It is resolved server-side, and a body that names a `from` is refused rather than ignored — so a request expecting a different sender never gets a success it would misread. - **The mail lands in the project owner's own verified account email**, the only address a sandbox send may reach. `to` is optional and defaults to it; any other value is refused. The same content scan and the same daily and trust-tier caps apply as on a real send. Unlike `send`, a test send takes no idempotency key. A project with no verified domain and no subscription gets **20 free test emails**. The response's `test_allowance` (`limit`, `used`, `remaining`) counts them down, and the 21st is refused with `quota_exhausted` naming `add_domain`; it is `null` once the project has a verified domain. ## Mailboxes, projects, and guided domain setup [#mailboxes-projects-and-guided-domain-setup] Three more capabilities are reachable with an API key: - **Mailbox reads** — `mailboxes.list()`, `mailboxes.get(id)` and `mailboxes.listAppPasswords(id)` (`list_app_passwords` in Python). `get` carries the IMAP and SMTP host, port, security and username a mail client needs; the mailbox password is never returned by any of them. App-password results are metadata only — `lastFour` identifies a credential without being enough to rebuild it — and cover only the passwords still active, not every one ever issued. These list the mailboxes themselves, never their contents: received messages are not part of the public API. See [List mailboxes](/api-reference/mailboxes/listMailboxes). - **The current project** — `projects.get()` takes no id and returns whichever project the key belongs to, including `sandbox_address` (the address a test send comes _from_). - **Guided domain setup** — `domains.startSetup(id)` (`start_setup`) begins the DNS hand-off and returns `{ token, connectUrl, expiresAt }` exactly as the API returns it. Finishing setup means a person opening `connectUrl` and authorising the change at their registrar, so the SDKs hand back the link rather than modelling the flow behind it. See [Guided DNS setup](/guides/guided-dns-setup). These, and the `/api/v1` send methods above, ship in `sendly-sdk` **1.0.0** on npm and `sendly-python` **1.0.0** on PyPI. Earlier releases (`0.4.0` / `0.2.0`) have neither. ## Operations the SDKs deliberately don't expose [#operations-the-sdks-deliberately-dont-expose] A handful of endpoints resolve the acting project admin from a **signed-in user** before they read any permission at all. An API key carries no user, so they answer `401` to any key however broad its scopes. Rather than ship methods that could never succeed, both SDKs leave them out: | Operation | Use instead | | ----------------------------------------- | ----------------------------------------------- | | Create or delete a mailbox | Dashboard, or an agent connected over OAuth | | Create or revoke a mailbox app password | Dashboard — there is no agent tool for these | | List, create, rotate or revoke an API key | Dashboard, or an agent connected over OAuth | | Create a project | Dashboard, or an agent connected over OAuth | This is a designed property, not a gap. Each repository's contract suite records these in a `NOT_SDK_CALLABLE` list and asserts it **equals** the set of operations the OpenAPI contract itself declares as session-only — in both directions, so an operation that becomes key-callable and a new key-refusing route that is missing from the list each fail the build. Wherever you create one — the dashboard or an OAuth-connected agent — the eleventh is refused with `409 Conflict`. The cap counts only mailboxes that hold, or are on their way to holding, a real account: `PROVISIONING`, `ACTIVE` and `SUSPENDED`. `FAILED` rows are excluded on purpose, so that a run of failed provisions cannot quietly spend a project's allowance and surface later as a limit error naming the wrong cause. Those failed rows *are* still returned by `mailboxes.list()`, so a project that has had failures can list more than ten. The same rule shapes the agent surface: where a matching [MCP](/guides/mcp) tool exists at all, it is never offered to a connection made with an API key and is reachable only over OAuth. ## Authentication [#authentication] Both SDKs authenticate with a project API key sent as a bearer token. Use a secret key (`sk_*`) for full access, or a public key (`pk_*`) for sending-only clients such as browser code. See [API Keys](/guides/api-keys) for where to find your keys and how the two differ. ## Staying in sync with the API [#staying-in-sync-with-the-api] The [API Reference](/api-reference/overview) on this site is generated from the same OpenAPI specification the SDKs are tested against. When the API changes, the spec and these reference pages regenerate together, and each SDK re-syncs its committed copy of the spec — its contract suite then fails until every new operation is mapped, so an SDK release that passes CI covers exactly the endpoints documented here. --- # Onboard your agent to Sendly (/agent-setup) Once connected, your agent can prove sending works right away: every new project gets **20 free test emails** to your own inbox with no domain, no DNS and no card, through the `send_test_email` tool or `POST /api/v1/emails/test`. When they run out, the refusal names `add_domain`, the next step. See [free test emails](/guides/verifying-domains#free-test-emails-before-you-verify). No account yet? The agent does not need one to show the user an email arriving: [the keyless start](/keyless-start) sends the same free test emails to the user's own inbox with no signup and no API key. The only thing the agent asks the user for is the 6-digit code from that inbox. ## Fastest: Claude's connector directory [#fastest-claudes-connector-directory] Using Claude on the web, desktop or mobile? Open Sendly's listing in Claude's connector directory, click **Connect**, then approve Sendly's sign-in. The connector syncs to Claude Desktop and mobile. ## Using ChatGPT? [#using-chatgpt] Sendly is a published ChatGPT app: Open Sendly in ChatGPT, click **Connect**, then approve Sendly's sign-in. ## Any coding agent: paste one sentence [#any-coding-agent-paste-one-sentence] Paste this sentence into any AI coding agent — Claude Code, Codex, Cursor, or anything else that can fetch a URL and run commands — and it sets itself up: The agent fetches https://docs.sendly.now/agent-setup/prompt.md — a Markdown file written for an agent to execute directly, not for a person to read — and follows it: get credentials, connect over MCP or the SDK, verify the connection, and report back to you. Every command in it is one you could also run yourself, from the pages below. ## Pick your agent [#pick-your-agent] Adds Sendly as a remote MCP server over Streamable HTTP. Adds Sendly as a remote MCP server over Streamable HTTP. Add Sendly to Cursor's MCP configuration. Add Sendly to Windsurf's MCP configuration. Add Sendly to OpenCode's MCP configuration. Add Sendly to VS Code's MCP configuration for Copilot's agent mode. Any client that speaks Streamable HTTP and OAuth 2.1 with PKCE can connect with no pre-registration. Not listed? Every client that speaks Streamable HTTP and OAuth 2.1 with PKCE can connect with no pre-registration — see [Any other MCP client](/agent-setup/other). --- # Onboard Claude Code to Sendly (/agent-setup/claude-code) --- # Onboard Codex to Sendly (/agent-setup/codex) --- # Onboard Cursor to Sendly (/agent-setup/cursor) --- # Onboard Windsurf to Sendly (/agent-setup/windsurf) --- # Onboard OpenCode to Sendly (/agent-setup/opencode) --- # Onboard VS Code / Copilot to Sendly (/agent-setup/vscode) --- # Onboard any other MCP client to Sendly (/agent-setup/other) --- # Contacts (/concepts/contacts) Contacts in Sendly represent an individual email recipient. Each contact has an identifier and is linked to an email address. ## Adding contacts [#adding-contacts] Contacts can be added to your Sendly project in several ways: - Using [/api/track](/api-reference/events/trackEvent), when tracking an event for a contact that does not yet exist, Sendly will automatically create it. - Using [/contacts](/api-reference/contacts/createContact), to create a single contact. - Import through CSV - Manually through the dashboard ## Contact Data [#contact-data] You can associate custom data with each contact using key-value pairs. This data can be used for segmentation and personalization. ### Data types [#data-types] Contact data types are inferred based on the value provided: | Type | Description | |------|-------------| | String | Any text value | | Number | Numeric values, including integers and floats | | Boolean | True or false values | | Date | Date values in ISO 8601 format | If you accidentally mix data types for a specific key, Sendly will default to treating the value as a string. ### Reserved keys [#reserved-keys] Certain keys are reserved by the system and automatically set by Sendly: | Key | Description | |-----|-------------| | email | The contact's email address | | createdAt | Timestamp of when the contact was created | | updatedAt | Timestamp of the last update to the contact | | subscribed | Boolean indicating if the contact is globally subscribed or not | ### Special keys [#special-keys] | Key | Description | |-----|-------------| | locale | The contact's preferred locale in ISO 639 (e.g. 'en', 'fr', 'es'). Specifying the locale field on a contact will override the project-wide locale for contact-facing pages and email footers | ## Subscription State [#subscription-state] Every contact has a `subscribed` field that determines which types of emails they will receive. A newly created contact is subscribed by default. ### How contacts become unsubscribed [#how-contacts-become-unsubscribed] A contact can become unsubscribed in several ways: - **Manually** through the dashboard or via the API - **Self-service** by clicking the unsubscribe link in an email - **Automatically** when an email to the contact bounces or results in a complaint ### Emails by subscription state [#emails-by-subscription-state] The subscription state controls whether a contact receives marketing emails. Transactional emails are always delivered regardless of subscription state. | Email type | Subscribed | Unsubscribed | |---|---|---| | **Transactional** (via [/api/emails](/api-reference/emails/sendEmail)) | Delivered | Delivered | | **Campaigns** (marketing) | Delivered | Not delivered | | **Campaigns** (self-managed unsubscribe) | Delivered | Not delivered | | **Campaigns** (transactional) | Delivered | Delivered | | **Automations** (marketing template) | Delivered | Not delivered | | **Automations** (self-managed-unsubscribe template) | Delivered | Not delivered | | **Automations** (transactional template) | Delivered | Delivered | Even when using the transactional API endpoint (`/api/emails`), you cannot send a marketing template to an unsubscribed contact. Use a transactional template instead if the email must reach unsubscribed contacts. --- # Segments (/concepts/segments) Segments let you create named groups of contacts that can be targeted in campaigns and used as triggers in workflows. There are two types: **Dynamic** and **Static**. ## Dynamic segments [#dynamic-segments] Dynamic segments evaluate a set of filter conditions against your contacts in real time. Membership is kept up to date automatically as contact data and events change — no manual work required. You can filter on: - Contact fields (`email`, `subscribed`, custom data fields like `data.plan`) - Contact dates (`createdAt`, `updatedAt`) - Custom events (`event.signed_up`, `event.purchased`, …) - Email activity (`email.opened`, `email.clicked`, `email.bounced`, …) Conditions can be combined with `AND`/`OR` logic and nested into groups for complex rules. ## Static segments [#static-segments] Static segments are manually curated lists. Membership does not change automatically — you decide exactly who is in the segment. This is useful for things like beta testers, event attendees, or any group imported from an external source. ## Creating a segment [#creating-a-segment] Go to **Segments** in Sendly and click **Create Segment**. Use the toggle at the top to choose **Dynamic** or **Static**. **For dynamic segments**, use the filter builder to define your conditions. Sendly will show you a live count of matching contacts. **For static segments**, you can optionally add initial members right away using the contact search. Start typing an email address and select contacts from the list — selected contacts appear as chips you can remove before saving. ## Managing static segment members [#managing-static-segment-members] Open a static segment and use the **Add Members** search to find and select contacts. The search looks up contacts already in your project, so you can't accidentally add someone who doesn't exist. Contacts already in the segment are greyed out. To remove a member, click the remove button on their row in the members list. ## Track membership changes [#track-membership-changes] Both segment types support **Track membership changes**. When enabled, Sendly fires a webhook event each time a contact enters or leaves the segment: - `segment.trial-users.entry` — contact joined the segment - `segment.trial-users.exit` — contact left the segment Where `trial-users` is derived from the segment name. See [Webhooks](/guides/webhooks) for the full event payload. ## Using segments [#using-segments] Segments can be used in: - Targeting contacts in [email campaigns](/concepts/campaigns) - Triggering workflows in [marketing automation](/concepts/workflows) ## Managing members via API [#managing-members-via-api] If you need to manage static segment membership programmatically, use the `POST /segments/:id/members` and `DELETE /segments/:id/members` endpoints. See the [API reference](/api-reference/overview#segments) for details. --- # Workflows (/concepts/workflows) Workflows in Sendly allow you to create automated email sequences that can be triggered based on events you send using the API. ## Prerequisites for workflows [#prerequisites-for-workflows] ### Sending an event [#sending-an-event] Workflows are triggered by sending events to Sendly using the [/api/track](/api-reference/events/trackEvent) endpoint. When sending an event, you can specify the contact it is associated with and include any relevant data. ### Creating a template [#creating-a-template] Before setting up the workflow, ensure you have created a template that will be used for the emails sent by the workflow. You can create templates in the [Templates](/concepts/templates) section of the dashboard. ## Creating a workflow [#creating-a-workflow] To create a workflow, navigate to the [Workflows](/concepts/workflows) section of the dashboard and create a workflow. In Sendly the trigger event is fixed once the workflow exists, so choose the event name carefully. Over the API it can be changed — `PATCH /api/v1/workflows/{id}` accepts `event_name` and `trigger_type` — and the change is refused with a `409` while any run is still in flight. ### Defining workflow steps [#defining-workflow-steps] Workflows consists of multiple steps that define the sequence of actions to be taken. | Step Type | Description | |-----------|-------------| | Send Email | Sends an email to the contact using a specified template. You can customize the email content using variables from the event data. | | Delay | Pauses the workflow for a specified duration before proceeding to the next step. | | Wait for Event | Pauses the workflow until a specified event is received for the contact. You can also set a timeout duration to proceed if the event is not received within that time. | | Condition | Evaluates a condition based on the event data or contact data and branches the workflow accordingly. | | Webhook | Sends a webhook to a specified URL with the event and contact data. | | Update Contact | Updates the contact's data with specified key-value pairs. | | Exit | Terminates the workflow for the contact, and stamps an exit reason on the run. | | Send at Optimal Time | Like Send Email, but held until this contact's historically best open hour, falling back to a fixed hour and never waiting longer than the step's maximum delay. | ## Managing workflow executions [#managing-workflow-executions] You can monitor and manage contacts going through workflows in the executions tab of the workflow detail page. Here you can see the status of each execution, cancel a specific execution or all executions. A workflow will be locked while there are active executions. If you want to make changes to a running workflow you will either need to pause it and wait for all executions to complete, or cancel all active executions. ## Automating workflows over the API [#automating-workflows-over-the-api] Everything above is also reachable over `/api/v1/workflows`, which is what an AI agent connected through the [MCP server](/guides/mcp) uses too: | What you want | How | |---------------|-----| | Create a workflow with its steps in one call | `POST /api/v1/workflows` with a `sequence` | | Change metadata, the trigger, or the whole sequence | `PATCH /api/v1/workflows/{id}` | | Read or replace a branching graph | `GET` and `PUT /api/v1/workflows/{id}/graph` | | Copy a workflow, steps and all, as a disabled draft | `POST /api/v1/workflows/{id}/clone` | | Stop it, and cancel the runs already inside it | `POST /api/v1/workflows/{id}/pause` | | Re-open it to new runs | `POST /api/v1/workflows/{id}/resume` | | See how the runs are going | `GET /api/v1/workflows/{id}/stats` | Setting `enabled` to false stops the workflow being *triggered* again and leaves every contact already part-way through it walking the steps: the next delay still expires and the next email still sends. `POST /api/v1/workflows/{id}/pause` does both, and reports how many runs it cancelled. Cancelling is terminal — resuming re-opens the workflow to new runs, it does not put the cancelled contacts back where they were. A `GET` on the graph endpoint returns a document that `PUT` accepts verbatim, so an edit is read, change one step, send it all back. The step ids in it are yours: an id you send back keeps that step and its run history, a new UUID adds a step, and an omitted step is deleted. See the [MCP guide](/guides/mcp#building-a-workflows-steps) for the full document and its rules. --- # Campaigns (/concepts/campaigns) Campaigns are a one-time email sent to a group of contacts. They are typically used for newsletters, announcements, or promotions. ## Targeting contacts [#targeting-contacts] When you create a campaign, you can send it to all subscribed contacts, or target a specific segment you have created in the [Segments](/concepts/segments) section. ## Sending a campaign [#sending-a-campaign] Once you have designed your campaign and selected the target audience, you can schedule it to be sent immediately or at a later time. You can also choose to send a test email to yourself or any other team member before sending it to your contacts. Campaigns will be queued and sent in the background. You can monitor the sending progress and view detailed analytics on opens, clicks, and bounces in the campaign detail page. Depending on the size of your audience, it may take some time for all emails to be sent. --- # Transactional Emails (/concepts/transactional-emails) Transactional emails are emails sent directly through the API. They are typically used for one-to-one communication, such as password resets, order confirmations, and notifications. ## Sending with attachments [#sending-with-attachments] Sendly supports sending attachments with transactional emails. You can include up to 10 attachments per email, with a maximum total size of 10MB. Attachments should be base64 encoded and included in the `attachments` array when sending the email via the [/api/emails](/api-reference/emails/sendEmail) endpoint. ## Sending from a template [#sending-from-a-template] You can also send transactional emails using a [template](/concepts/templates) you have created in Sendly. This allows you to reuse the same design and content for multiple emails, while still personalizing them with contact data. --- # Templates (/concepts/templates) Templates are stored in the Sendly dashboard and can be used in campaigns, workflows and transactional emails. ## Designing templates [#designing-templates] Templates can be created using the built-in editor or by uploading your own HTML. ### Personalization [#personalization] You can use contact data to personalize your templates by using the handlebars syntax `{{ key }}`, where `key` is the contact data key. #### Always Available Variables [#always-available-variables] These variables are always available in your templates, regardless of custom contact data: | Variable | Description | | -------------------- | -------------------------------------- | | `{{id}}` | The contact's unique identifier | | `{{email}}` | The contact's email address | | `{{unsubscribeUrl}}` | URL to the unsubscribe page | | `{{subscribeUrl}}` | URL to the subscribe/resubscribe page | | `{{manageUrl}}` | URL to the preferences management page | #### Fallback Values [#fallback-values] You can provide fallback values for variables that might not be set: ``` Hello {{firstName ?? 'there'}}! ``` If `firstName` is not set, this will render as "Hello there!" #### Special Fields [#special-fields] The following fields are reserved by Sendly but can still be used. | Variable | Description | | ---------------- | --------------------------------------------------- | | `{{subscribed}}` | Contact's subscription status (true/false) | | `{{locale}}` | Contact's preferred locale (e.g., 'en', 'fr', 'es') | ### Previewing templates [#previewing-templates] You can preview your templates by selecting a contact in the preview window. This will allow you to see how the template will look for that specific contact, with their data populated. ## Templates types [#templates-types] There are three types of templates in Sendly. Each type is treated at the same priority when sending emails, you should not pick one type over the other based on deliverability or performance. | Type | Respects opt-out | Sendly unsubscribe footer | Description | | ------------- | :--------------: | :----------------------: | -------------------------------------------------------------------------------------------------------------------- | | Marketing | Yes | Yes | Automatically includes a Sendly-hosted unsubscribe footer. Will not be sent to contacts who are unsubscribed | | Transactional | No | No | Does not include any way to unsubscribe. Will be sent to any contact, regardless of subscription state | | Headless | Yes | No | Respects opt-out like marketing, but no Sendly footer is appended. You are responsible for providing an unsubscribe mechanism in the email body. Use `{{unsubscribeUrl}}` or `{{manageUrl}}` to link to Sendly's managed unsubscribe page | --- # Billing (/concepts/billing) Sendly bills on the number of emails sent each month. Marketing and transactional mail are billed the same way, under the same plan — there is nothing to pick between and no plan tier to outgrow. ## Free tier [#free-tier] Every project starts free and stays free until you choose otherwise. A free project can send up to **5,000 emails per calendar month** at no cost, with no card required. That allowance is **shared across every kind of email** the project sends — campaigns, workflow emails, transactional sends, and inbound mail all draw from the same 5,000. The counter resets on the first of each month. Free projects are content-scanned on every send rather than on a sample. That is the trade that makes an allowance this size workable, and it applies to the project's own outbound mail only. Emails sent from a free project carry a small **"Sent with Sendly"** line in the footer. Upgrading removes it. When a project reaches the cap, further sends are refused until the month rolls over or you upgrade. Sendly emails the project's members at 80% of the allowance and again when it is reached, so the block is never a surprise. ## Pay as you go [#pay-as-you-go] Upgrading puts the project on a single metered plan with **no monthly fee**. You pay for the emails you actually send, and the rate drops as you send more: | Emails in a month | Rate per 1,000 | | ----------------- | -------------- | | First 50,000 | **$1.00** | | Next 200,000 | **$0.70** | | Above 250,000 | **$0.50** | The bands are **graduated**, so passing a threshold does not re-price the emails below it — it only changes the rate for the ones above. A month of 100,000 emails is 50,000 at $1.00 per 1,000 plus 50,000 at $0.70 per 1,000, which is **$85.00**. A month of 1,000,000 is **$565.00**. There is no monthly email cap, no plan to pick, and no per-contact fee. The table above is in US dollars. You are quoted and charged in your own currency: **USD, CAD, EUR, GBP, AUD, BRL, MXN, JPY** and **PHP** each carry their own price, picked from the country your account was opened in and changeable in the Billing tab. A country with no local price — India, Nigeria and Pakistan among them — is quoted and charged in US dollars, and the dashboard says so on the page where you pick. Checkout is per project. Billing periods are anchored to the first of the month. Each project carries its own subscription. Upgrading one project does not change the free-tier cap on another project in the same account. ## Sending limits [#sending-limits] Two limits exist alongside the monthly allowance, and they apply to free and paid projects alike: - **A daily sending ceiling** that scales with how established the project is. New projects start with a deliberately tight daily cap; it rises as the project ages and once it has a verified sending domain or an active subscription. This is an anti-abuse control, not a billing tier. - **An account-wide daily budget** across every project you own, so creating extra projects does not multiply your ceiling. If you need more headroom than these allow — a launch, a migration, a genuinely high-volume workload — email [support@sendly.now](mailto:support@sendly.now). We review accounts individually and can set custom limits by hand. ## Monitoring your usage [#monitoring-your-usage] The **Billing** tab in project settings shows current usage against your allowance, and lets you set your own limit per category (campaigns, workflows, transactional, inbound). Those limits are yours, not ours: use them to cap what a runaway integration can spend. You can also read the same numbers over the API at [`GET /api/v1/usage`](/api-reference/overview). ## What counts as an email [#what-counts-as-an-email] - Each recipient of a send counts as one email. - **Inbound** emails count at the same rate as outbound ones. - Attachments do not change the count — an email with an attachment is one email. --- # List Hygiene (/guides/list-hygiene) Sendly automatically monitors the bounce and complaint rates of your emails to help maintain a health sender reputation. High bounce or complaint rates can negatively impact your deliverability and may lead to your account being suspended. ## Bounce Management [#bounce-management] A bounce occurs when an email cannot be delivered to the recipient's inbox. When an email bounces, Sendly will automatically unsubscribe the contact and also send an event on the contact for `email.bounced`. ### Types of Bounces [#types-of-bounces] | Type | Description | |------|-------------| | Hard Bounce | Permanent delivery failure (e.g., invalid email address) | | Soft Bounce | Temporary delivery failure (e.g., mailbox full) | ### Preventing bounces [#preventing-bounces] - [Verify email addresses](/api-reference/verify/verifyEmailAddress) - Regularly clean your email list - Use double opt-in for subscriptions ## Complaint Management [#complaint-management] A complaint occurs when a recipient marks your email as spam. When a complaint is received, Sendly will automatically unsubscribe the contact and send an event on the contact for `email.complaint`. ### Preventing complaints [#preventing-complaints] - Ensure your emails are relevant and valuable to your audience - Include a clear unsubscribe link in every email - Monitor your email frequency to avoid overwhelming your contacts --- # Verifying sending domains (/guides/verifying-domains) Before Sendly sends mail from your own [sending domain](/glossary/sending-domain), that domain has to be verified. Verification is also what lets receivers authenticate your mail, which is most of what keeps it out of the spam folder. ## Free test emails before you verify [#free-test-emails-before-you-verify] You do not need a domain to try Sendly. Every new project can send **20 free test emails** from its sandbox address (`@sendly.now`) with no domain, no DNS and no billing: the dashboard's **Send me a test email** button, `POST /api/v1/emails/test`, or the `send_test_email` tool for an AI agent. Test emails only ever reach **your own verified account email**, so they cannot be used to mail anyone else. One network can send at most 100 a day across all projects. When the 20 are used up, a test send is refused with `quota_exhausted` (status `403`, code `SANDBOX_ALLOWANCE_EXHAUSTED` on the older `/api` routes) and `next: add_domain`. Verify a domain as described below: a verified domain sends to anyone on the free plan, no card needed, and test sends then keep working under the normal daily cap. ## What is a sending domain? [#what-is-a-sending-domain] A [sending domain](/glossary/sending-domain) is the domain in the address your mail comes from: `yourdomain.com` in `hello@yourdomain.com`. It can be your root domain or a subdomain such as `mail.yourdomain.com`; each one you add is verified on its own and keeps its own reputation with mailbox providers. Verifying it means publishing DNS records that prove you control it. Sendly asks for three kinds, each covered below: - **DKIM** — 3 CNAME records that let receivers verify the DKIM signature your mail is sent with. These decide verification. - **Custom MAIL FROM** — an MX and an SPF TXT record on `sendly.yourdomain.com`, the subdomain your [Return-Path](/glossary/return-path) (envelope sender) uses, so SPF aligns with your domain. - **DMARC** — one TXT record stating your policy for mail that fails both checks. ## Verifying a domain [#verifying-a-domain] You can verify a domain by adding it in the domain tab of the project settings. Once added, Sendly will provide you with the necessary DNS records to add to your domain's DNS settings. Once you have added the DNS records, it may take some time for the changes to propagate. You can check the verification status in the domain tab of the project settings. You don't have to copy and paste any of this. **Guided setup** hands the whole record set to a connect flow that writes it into your zone (one click on Cloudflare) or walks you through your own provider's interface — and then keeps watching the records afterwards. See [guided DNS setup](/guides/guided-dns-setup). ## DNS Records [#dns-records] Domain verification requires adding several DNS records to your domain. Each record serves a specific purpose in email authentication and delivery. Every value in the table below has a copy icon next to it in Sendly — use it rather than retyping. ### DKIM Records (3 CNAME records) [#dkim-records-3-cname-records] **DomainKeys Identified Mail (DKIM)** adds a digital signature to your emails, proving they haven't been tampered with during transit. You'll need to add **3 CNAME records** provided by Sendly. These records contain cryptographic keys that email receivers use to verify your emails are authentic. | Type | Name | Value | | --- | --- | --- | | CNAME | `._domainkey.yourdomain.com` | `.dkim.amazonses.com` | These are the records that decide verification: the domain flips to **Verified** when Amazon SES reads them back. **Why it matters:** - Prevents email spoofing and tampering - Improves deliverability and inbox placement - Required by most email providers (Gmail, Outlook, etc.) ### Custom MAIL FROM (1 MX + 1 TXT record) [#custom-mail-from-1-mx--1-txt-record] Sendly sets a **custom MAIL FROM subdomain** — `sendly.yourdomain.com` — on every sending identity. Both of the following records belong on that subdomain, **not** on your root domain: | Type | Name | Value | | --- | --- | --- | | MX | `sendly.yourdomain.com` | `10 feedback-smtp..amazonses.com` | | TXT | `sendly.yourdomain.com` | `"v=spf1 include:amazonses.com ~all"` | The dashboard fills in your deployment's actual AWS region. The **MX** record is how bounce and complaint reports get back to your own subdomain; the **TXT** record is the **SPF** policy that authorizes Amazon SES to send for it. **Why it matters:** - Bounces and complaints are attributed to your domain instead of Amazon's - SPF aligns with your domain, which is what DMARC actually checks - Automatically tracks which contacts have bounced or complained - Prevents sending to invalid email addresses If the MX record is missing, SES quietly falls back to `amazonses.com` as the envelope sender. Your emails still send — which is exactly why this is easy to miss — but bounce and complaint reports don't reach your subdomain and SPF no longer aligns with your domain for DMARC. The dashboard marks the section **ACTION REQUIRED** until SES reports the subdomain as active. ### DMARC Policy (1 TXT record) [#dmarc-policy-1-txt-record] **Domain-based Message Authentication, Reporting and Conformance (DMARC)** tells receivers what to do with mail that claims to be from your domain but fails DKIM and SPF. | Type | Name | Value | | --- | --- | --- | | TXT | `_dmarc.yourdomain.com` | `v=DMARC1; p=none;` | Sendly prescribes `p=none` on purpose. It is a **monitor-only** policy: it changes nothing about how receivers treat your mail, so publishing it cannot break a domain that is already sending — while still making `_dmarc` present, which some receivers weigh. Once you're confident you know *every* system that sends as your domain (your app, your CRM, your invoicing tool, your helpdesk), you can tighten it to `p=quarantine` and then `p=reject` yourself. Starting at `p=reject` before that inventory exists is how legitimate mail gets thrown away. ### Inbound Email (1 MX record) [#inbound-email-1-mx-record] This **MX record**, on your root domain, decides where mail addressed **to** your domain is delivered. It is separate from the MAIL FROM MX above and is not required for sending. Adding this record replaces your domain's current mail delivery — don't add it if your domain already receives email through Google Workspace, Microsoft 365 or anything else. See the [receiving emails](/guides/receiving-emails) guide for the full setup. ## Verification Status [#verification-status] After adding all DNS records, Sendly will automatically check the verification status. Verification typically completes within a few minutes but can take up to 72 hours depending on DNS propagation. You can check the status in the Domains section of your project settings: - The domain shows a **Verified** or **Pending** badge. **Amazon SES is the only authority on this** — the badge flips when SES confirms your DKIM records, not when your DNS provider says the records were saved. - The **DNS Health** row shows a chip per record family: **DKIM**, **SPF**, **DMARC** and **MAIL FROM**, plus the date of the last check. Sendly re-checks these on its own schedule; the refresh button on the domain row runs a check immediately. - If [guided setup](/guides/guided-dns-setup) is connected, an amber **DNS Drift** chip appears when a record you had published stops resolving. ## Troubleshooting [#troubleshooting] ### Records not verifying [#records-not-verifying] If your DNS records aren't verifying after 24 hours: 1. **Double-check the values**: Ensure you copied the exact values without extra spaces 2. **Check you're in the right zone**: If your domain's DNS is delegated to a subdomain or a second provider, the records must go in the zone that actually answers for the name shown in the table 3. **Watch for auto-appended domains**: Many DNS panels append your domain to whatever you type. Pasting the full name into such a field produces `sendly.yourdomain.com.yourdomain.com` 4. **Check DNS propagation**: Use tools like `dig` or online DNS checkers to verify the records are published 5. **TTL settings**: Some DNS providers cache records. Try lowering the TTL (Time To Live) value 6. **Contact your DNS provider**: Some providers have specific requirements or interfaces for adding these record types ### MAIL FROM says "ACTION REQUIRED" [#mail-from-says-action-required] SES isn't using your `sendly.yourdomain.com` subdomain yet. The notice in that section names the exact state: | State | What it means | What to do | | --- | --- | --- | | **Waiting for DNS** | SES hasn't found the MX record yet | Publish the MX and TXT records; SES re-checks automatically | | **Temporarily unreadable** | SES couldn't read the MX record on its last attempt and will retry | Confirm the record is published and your DNS provider is answering for that subdomain | | **Setup failed** | SES gave up looking for the MX record | Add the MX record, then use the refresh button to re-check | | **Not configured** | The identity has no custom MAIL FROM subdomain at all | Use the refresh button; if it stays unconfigured, remove and re-add the domain | In every one of these states your mail still sends — with `amazonses.com` as the envelope sender. ### The DNS Drift chip appeared [#the-dns-drift-chip-appeared] A record you had successfully published stopped resolving. This is usually a DNS record deleted during unrelated cleanup, a provider migration that didn't carry every record across, or a zone that was rebuilt from an older export. Drift does **not** un-verify your domain — SES may still consider the identity verified because of caching and TTLs — but it is an early warning that sending will start failing. Open the DNS records table, re-publish the records that no longer match, and use **Re-check DNS** to ask for an immediate re-check. See [drift monitoring](/guides/guided-dns-setup#drift-monitoring). ### Emails still going to spam [#emails-still-going-to-spam] Even with a verified domain, emails may go to spam if: - Your content triggers spam filters (excessive links, suspicious keywords) - Your sender reputation is new or low - Recipients have marked your emails as spam in the past - You're sending to invalid or unengaged contacts Follow email best practices and maintain good [list hygiene](/guides/list-hygiene) to improve deliverability. --- # Sending identities (/guides/sending-identities) A **sending identity** is one verified domain. It has its own DKIM keys, its own MAIL FROM subdomain, and — the part that matters — its own reputation with Gmail, Outlook and everyone else. Most senders start with one. That is fine until the day a campaign draws complaints, because mailbox providers do not distinguish your newsletter from your password resets when both leave from `example.com`. The reset lands in spam, and the first you hear about it is a support ticket. Splitting the traffic across two identities keeps that from happening. A common shape: | Identity | Stream | Carries | | ------------------- | --------------- | ------------------------------------------ | | `mail.example.com` | `TRANSACTIONAL` | Receipts, password resets, alerts, invites | | `news.example.com` | `MARKETING` | Campaigns and newsletters | Both are subdomains of one root you already own, so both are one DNS zone and one set of records to publish. ## Adding one [#adding-one] Add a domain the way you always have, in **Settings → Domains**. Once Sendly can see the root you are typing, it offers `mail.` and `news.` and says what each is for. Picking one assigns the stream and makes it your default for that stream in the same step. The root itself is still addable, and it is still the fallback. A domain with no stream carries both, which is exactly what every domain added before this feature does. Existing domains keep working unchanged. They carry both streams until you say otherwise, and assigning a stream is a decision you make when you are ready to make it. ## What the assignment actually does [#what-the-assignment-actually-does] It is enforced, not a label. - **A send with no `from` address** goes out on your default identity for its stream, using that identity's default sender. Transactional sends resolve the transactional identity; campaigns resolve the marketing one. - **A send that names a `from` address** uses it — that is the per-send override — but the address still has to be on an identity your project owns AND one that carries this stream. Sending a campaign from your transactional identity is refused with `403`, naming the identity and both streams. So the separation is a property of the mail, not a setting somebody has to remember. ```bash title="Refused: a campaign from the transactional identity" curl -X POST https://api.sendly.now/api/v1/campaigns \ -H "Authorization: Bearer $SENDLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "September", "from": "hello@mail.example.com", ... }' # 403 # "mail.example.com" is the transactional sending identity for this project, so it cannot # carry marketing mail. Send from the marketing identity, or unassign this one to let it # carry both. ``` ## Assigning a stream over the API [#assigning-a-stream-over-the-api] `PATCH /api/domains/{id}` takes the four fields together. Every one is optional, and an omitted field is left alone. ```bash title="Make news.example.com the marketing identity" curl -X PATCH https://api.sendly.now/api/domains/$DOMAIN_ID \ -H "Authorization: Bearer $SENDLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "stream": "MARKETING", "streamDefault": true, "defaultFromAddress": "news@news.example.com", "defaultFromName": "Acme News" }' ``` | Field | What it means | | -------------------- | ------------------------------------------------------------------------------------------------------ | | `stream` | `TRANSACTIONAL`, `MARKETING`, or `null` to unassign and carry both | | `streamDefault` | Make this the project's default for that stream. Setting it demotes whichever held it | | `defaultFromAddress` | The address a send on this stream uses when it names none. Must be on this identity's host | | `defaultFromName` | The sender name recipients see when a send names none. Up to 100 characters; `null` or `""` clears it | ## The sender name recipients see [#the-sender-name-recipients-see] The inbox shows a name beside the address: `Acme News `. Sendly picks that name in this order: 1. The send's own name: `from: { "email": ..., "name": ... }` or `name` on `POST /api/v1/emails`. 2. The from-name on the template the send uses. 3. The `defaultFromName` on the identity the address is on. 4. The project name. `defaultFromName` belongs to the identity, not to a stream. It applies to every send leaving on that host, and unassigning the identity keeps it. Set it once and every send that doesn't name itself goes out under your brand name instead of your project's internal name. It needs the `domains:write` scope, the same as adding or removing a domain. The name has a picture to go with it: every identity also has a [sender logo](/guides/sender-logo) that mailboxes supporting BIMI show beside the name, and its default is titled with this name. `defaultFromAddress` must be an address on the identity you are setting it on — `news@news.example.com`, not `news@example.com`. An address on a different host would be signed by a different identity's DKIM keys, or by none, which is the failure the identity exists to prevent. ## Verification [#verification] Each identity verifies on its own, because each is a separate SES identity. Adding `news.example.com` gives you a separate DKIM record set to publish, and the domain page shows its DKIM, SPF, DMARC and MAIL FROM status independently of the root's. Until an identity verifies, no send falls back to it. An unverified default is skipped rather than used, so an assignment made ahead of DNS never puts mail out unsigned. See [verifying domains](/guides/verifying-domains) for the record set, and [guided DNS setup](/guides/guided-dns-setup) to have them published for you. ## Subdomains and your account standing [#subdomains-and-your-account-standing] Adding identities does not change your sending limits. Sendly counts **registrable domains**, not domain rows, when it works out how much of your domain setup you have proved — three identities under `example.com` count as the one domain they are. Splitting your streams is a deliverability decision, and it is not a way to buy volume. --- # Sender logo (/guides/sender-logo) Most inboxes show a grey initial next to a message from a sender they have no picture for. A mailbox that supports **BIMI** (Brand Indicators for Message Identification) shows your logo instead, and a recognisable face in a list of messages is one of the few things that changes whether yours gets opened. Every sending identity in Sendly has a logo already. Until you upload one, it is your domain's initial on a coloured square. A provider may display it once its BIMI requirements are met. ## What it takes [#what-it-takes] Start with these three prerequisites; some providers also require certification (see below): 1. **The file.** Your upload, or the default initial. Sendly hosts it at a URL that belongs to the identity and never changes. 2. **A TXT record** in your DNS, naming that URL. You publish it once. 3. **An enforced DMARC policy**: `p=quarantine` or `p=reject`, applied to all of your mail (no `pct` below 100). A mailbox will not put a logo on mail from a domain whose owner has not said what to do with forgeries. **Settings → Domains → Sender logo → Set up** shows the file, gives you the record to copy, and reads the other two back from public DNS, in words that say what to change. The logo is served only once the identity **verifies**, and not at all while the project is disabled. An upload alone proves only that someone typed the domain into a form; serving a logo before the domain proves it is yours would let anyone put a brand's face on mail that is not theirs. ## The record [#the-record] ```txt title="One TXT record per identity" Name: default._bimi.news.example.com Value: v=BIMI1; l=https://app.sendly.now/bimi/.svg; ``` The panel shows the exact name and value for each identity. Each identity gets its own record, at its own host, so `mail.example.com` and `news.example.com` can carry different logos. If you publish a record at the root (`default._bimi.example.com`) instead, every host under it that has no record of its own falls back to that one. Replacing or removing the logo later changes what the URL serves. It does not change the record, so there is nothing to republish. ## Uploading a logo [#uploading-a-logo] Upload an SVG from the panel, or over the API. Sendly rebuilds it into **SVG Tiny PS**, the restricted profile mailboxes require, and that rebuilt file is what the URL serves. The rebuild drops what design tools add for their own use and keeps the shapes. The file has to: - be **square**: the mailboxes crop it to a circle, so keep the mark inside the middle; - draw with shapes. `` renders only in fonts the reader happens to have, so it is refused: convert text to outlines before exporting; - reference nothing outside itself: no embedded images, no links, no external fonts; - come to **32 KB or less** after the rebuild. A file that does not fit is refused with the reason, and the logo you had stays in place. ```bash title="Upload a logo" curl -X PUT https://api.sendly.now/api/v1/domains/$DOMAIN_ID/logo \ -H "Authorization: Bearer $SENDLY_API_KEY" \ -H "Content-Type: application/json" \ -d "$(jq -n --rawfile svg logo.svg '{svg: $svg}')" ``` The answer carries the file as served, the record to publish (`bimi_record`), and a fresh DNS reading (`readiness`). `GET` the same path to read them again, and `DELETE` it to go back to the default. Uploading and removing need the `domains:write` scope; reading needs `domains:read`. ## Through MCP [#through-mcp] Use `get_domain_logo` with the sending domain's ID to read its logo, BIMI record and live DNS checks (`domains:read`). Use `upload_domain_logo` with `domainId` and square vector `svg` source to replace it (`domains:write`). The upload uses the same validation as the UI and API. It affects the domain and its mailboxes; it does not change DNS or obtain a certificate. A PNG logo can be used **inside** a rich email through `document.brand.logoUrl`. An inbox sender logo needs a suitable vector SVG instead; wrapping a PNG in an SVG does not qualify. ## Which inboxes show it [#which-inboxes-show-it] Providers decide whether to display a sender logo. Published BIMI and enforced DMARC are prerequisites, not a guarantee that every recipient sees it. Yahoo and AOL also consider sender reputation and engagement; see their [BIMI requirements](https://senders.yahooinc.com/bimi/). Gmail additionally requires a **Verified Mark Certificate (VMC)** or **Common Mark Certificate (CMC)** issued by a certificate authority, with its associated files published as required by [Google's setup guide](https://knowledge.workspace.google.com/admin/security/set-up-bimi). Apple Mail does too: its mail provider must have verified a BIMI Evidence Document (for example a VMC) before Apple Mail shows the logo, per [Apple's BIMI requirements](https://developer.apple.com/support/bimi). Sendly does not issue or validate these certificates. Its **DNS ready** badge reports only the logo's availability and DNS checks. Other inbox providers have their own display requirements. Mailboxes cache what they fetch. A new upload can take a day or more to appear in an inbox that has already shown your old one. ## Check what is still missing [#check-what-is-still-missing] [`GET /api/v1/domains/{id}/logo/readiness`](/api-reference/domains/v1GetDomainLogoReadiness) (`domains:read`) answers, step by step and inbox by inbox, what is in place and what is not: | Step | `met` when | | --------------------- | -------------------------------------------------------------------------------------------------- | | `dmarc_enforced` | DMARC is `p=quarantine` or `p=reject` at `pct=100`, on the sending host and its registered domain | | `bimi_record` | a `default._bimi` TXT record exists and its `l=` is an https URL | | `logo_file` | the file at `l=` is SVG Tiny PS (Sendly checks the file it serves, and fetches a file you host) | | `mark_certificate` | the record's `a=` URL answers with a PEM file; the certificate chain itself is not validated | | `gmail_profile_photo` | never: a Google account photo on the exact From address is set by the sender and cannot be seen | | `apple_branded_mail` | never: it is registered with Apple (Apple Business), not published in DNS, and cannot be seen | Each step carries a plain-English `reason` when it is not `met`, the inboxes it `unlocks`, and `evidence` (what was read). A step is `unknown` when a lookup failed or it is self-attested with the provider: it is never a pass and never a failure, so check again in a minute. `providers` has one checklist per inbox (Gmail, Yahoo, Apple Mail, Fastmail) saying which steps that inbox `required`, treats as `optional`, or offers as an `alternative` route. The reading comes from public DNS and from the hosts your record names, and ends after 5 seconds whatever they are doing (a step it had not finished is `unknown`), so it is held for a minute: `checked_at` says when it was taken. `ready` means every required step is met, which is still not a promise: providers decide whether to display a logo. ## The name beside it [#the-name-beside-it] The logo sits next to the sender **name**, which you set per identity as well, with `defaultFromName`. See [the sender name recipients see](/guides/sending-identities#the-sender-name-recipients-see). The default monogram is titled with that name too, or with the project name when the identity has none. --- # Warming up a domain (/guides/warming-up-a-domain) A brand-new sending domain has no reputation. The first thing Gmail, Outlook and the rest learn about it is the volume it opens with, and the pattern they are most confident about is the one that looks like this: nothing, then thousands, from a domain nobody has ever seen. So Sendly starts every newly verified identity on a **warm-up**: a daily ceiling that begins small and rises every day for 30 days. It is not a plan you follow by hand. The send path enforces it, per identity, per UTC day. ## The ramp [#the-ramp] | Day | Emails that identity may send | | --- | ----------------------------- | | Day 1 | 50 | | Day 2 | 100 | | Day 3 | 200 | | Day 7 | 1,000 | | Day 14 | 7,500 | | Day 21 | 25,000 | | Day 30 | 50,000 | The days in between step up gradually. After day 30 the identity graduates and carries no warm-up ceiling at all. These are ceilings, not targets. Sending less than the day's number is normal and costs you nothing — what the mailbox providers react badly to is a sharp day-over-day *increase*, which a ceiling can prevent and a target cannot. A warm-up is one of three limits on a send, not a replacement for them. Your project's daily cap and your account's sending rate still apply, and the smallest of the three is the one you will hit. That is why the panel tells you which one is holding you: if your account's rate is lower than the ramp asks for on a given day, raising the ramp would change nothing. ## Where to see it [#where-to-see-it] **Settings → Domains**, on the identity itself. It shows the day you are on, today's ceiling, how much of it you have used, and which of the two limits produced the number. A send past the day's ceiling fails with a message naming the identity and the day. It is not retried: the ceiling is a daily one, so the send would fail again on every attempt until tomorrow. Send the rest of that batch the next day. ## Ending a warm-up early [#ending-a-warm-up-early] If the domain already sends from another provider, it already has a reputation, and opening it at 50 a day is a regression rather than a protection. **End warm-up** on the domain lifts the ceiling immediately. Do that only when it is true. A domain that has never sent, released straight to full volume, is exactly the pattern the ramp exists to prevent, and the damage — a reputation formed on a bad first week — takes far longer to undo than the 30 days you saved. ## Starting one again [#starting-one-again] **Start from day one** puts an identity back at the beginning of the ramp. Two situations call for it: - The identity has gone quiet for months. Reputation decays, and resuming at volume reads the same to a mailbox provider as starting from nothing. - The identity's reputation took damage — a bad list, a spike in complaints — and you are rebuilding it deliberately. Restarting does not clear what you have already sent today. Those messages happened, and handing back the day's headroom would begin the restart with a burst. ## Identities added before warm-ups existed [#identities-added-before-warm-ups-existed] They are not enrolled, and nothing changed for them. A warm-up starts when a domain **verifies**, so only identities verified from here on begin one automatically. An older identity can be put on a ramp with **Start from day one** if you want it there. --- # Guided DNS setup (/guides/guided-dns-setup) Publishing DKIM, MAIL FROM and DMARC records by hand is the step where most domains stall — a typo in a CNAME, a record added to the wrong zone, or a trailing dot in the wrong place, and the domain never verifies. Guided setup removes the copying and pasting: Sendly hands the exact record set to a DNS connect flow that either writes the records into your zone for you or walks you through your own provider's interface, one record at a time. Guided setup is powered by [DoDomain](https://dodomain.io), and it also keeps watching your zone after setup finishes, so a record that quietly disappears months later becomes a notification instead of a mystery bounce. Guided setup only appears when it is enabled on the deployment you're using. It is on for Sendly Cloud. A self-hosted Sendly needs a `DODOMAIN_SECRET_KEY` (and `DODOMAIN_WEBHOOK_SECRET` for drift monitoring) configured — without them no button is drawn at all, and the [manual record path](/guides/verifying-domains) is the only path. If the feature is turned off after a session was started, Sendly reports **"Guided DNS setup is not available on this deployment."** ## Starting guided setup [#starting-guided-setup]
### Add the domain [#add-the-domain] In your project settings, open the **Domains** tab and add your domain in the **Add Domain** card. Sendly creates the SES sending identity, generates the DKIM tokens, and expands the record table for the new domain straight away. ### Choose the automatic path [#choose-the-automatic-path] On a domain you have just added, the record table opens with a callout at the top: > **Let us publish these records for you** > We'll take you through your DNS provider and add every record below — no copying and pasting. Press **Set up automatically** to start. **I'll do it manually** dismisses the callout for that domain and leaves you with the copy-paste table. You can also start the flow at any time from the **Guided setup** button in the header of the record table — it sits next to the **DNS Configuration Required** / **View DNS Records** toggle. ### Read the provider hint [#read-the-provider-hint] Before you commit, Sendly runs a free pre-flight against your domain's nameservers and prints a small hint under the **Guided setup** button: | Hint | What it means | | --- | --- | | `One-click available · Cloudflare` | Your zone is on a provider Sendly can write every record to. Authorize the connection and you're done. | | `Guided steps` | Sendly can't write to this provider, so the flow shows step-by-step instructions for your specific DNS host instead. | The hint is deliberate: "one-click" promised and not delivered is worse than never promising it. The pre-flight only reads your nameservers — it creates nothing and costs nothing. ### Complete the flow [#complete-the-flow] The connect flow opens in a sheet over the dashboard, themed to match it. If your browser blocks the embed (a content blocker, a strict CSP, an offline tab), Sendly opens the same flow in a new tab instead — nothing is lost. When the flow finishes it returns you to your **Domains** settings. ### Let Sendly re-check the domain [#let-sendly-re-check-the-domain] As soon as the records land, Sendly re-checks the domain against Amazon SES automatically. The **Verified** badge flips when SES confirms the DKIM records — not when the connect flow says it published them.
## What guided setup publishes [#what-guided-setup-publishes] The record set is the same one the [records table](/guides/verifying-domains#dns-records) shows, in the same order — there is no second, hidden prescription: - the **3 DKIM CNAMEs** at `._domainkey.yourdomain.com` - the **custom MAIL FROM MX and SPF TXT** at `sendly.yourdomain.com` - the **DMARC TXT** at `_dmarc.yourdomain.com` (`v=DMARC1; p=none;`) - the **inbound MX at your root domain**, but *only* when your project uses Sendly mailboxes The root-domain MX record is the one record in the set that could redirect your company's existing email (Google Workspace, Microsoft 365). Guided setup only ever writes it when Sendly mailboxes are configured for the deployment — the legacy inbound-email MX stays a copy-paste row you opt into deliberately, and is never automated. See [receiving emails](/guides/receiving-emails). ## One-click versus guided steps [#one-click-versus-guided-steps] Sendly asks DoDomain which *tier* your DNS provider qualifies for, and only the top tier is treated as automatic: - **Cloudflare (one-click).** You authorize the connection against your Cloudflare account and the full record set — CNAME, MX, TXT — is written into your zone for you. - **Every other provider (guided steps).** The flow identifies your provider and shows the records with instructions written for that provider's control panel. You still paste the values, but into the right screen with the right field names. Providers that support Domain Connect fall into the second group on purpose. Domain Connect's automated templates can only carry a single CNAME or a verification TXT — they can never write MX, SPF, DKIM or DMARC, and every record Sendly prescribes is one of those. ## Drift monitoring [#drift-monitoring] After a successful connection, DoDomain keeps checking the records it published. Sendly's own resolver sweep runs every six hours; drift monitoring is what watches the zone in between. When a record that *was* resolving stops resolving: - an amber **DNS Drift** chip appears in the domain's **DNS Health** row, beside the DKIM / SPF / DMARC / MAIL FROM chips. Its tooltip reads: *"A record you published stopped resolving. Open the DNS records below and re-publish the ones that no longer match."* - a **Domain DNS Drift Detected** notification is sent to the project's members — in the notification bell and as a push, deep-linked to the Domains settings — and to your operators' alert channel. - a **Re-check DNS** button appears next to **Guided setup** in the record table header. - **Guided setup** is offered again, even on a domain that is already verified, so you can re-publish the missing records the same way you published them the first time. Drift never changes the **Verified** badge. Amazon SES is the only authority on verification, and SES may still consider the identity verified at that moment because of DNS caching and TTLs. Drift is an early warning that a record went missing — act on it before SES notices and sending starts failing. ### Re-check DNS [#re-check-dns] **Re-check DNS** asks DoDomain to look at your zone again right now instead of waiting for its next scheduled pass. It is a request, not an answer: the check runs on their side and the verdict arrives a moment later, which is why the confirmation reads **"Re-check started — we'll update the status automatically."** The chip clears itself once the records resolve again. Asking twice in quick succession is refused with **"This domain was just re-checked. Give DoDomain a few minutes before asking again."** — a wait, not a failure. ## Troubleshooting [#troubleshooting] ### The Guided setup button isn't there [#the-guided-setup-button-isnt-there] Three reasons, in order of likelihood: 1. **The domain is already verified and healthy.** There is nothing to guide, so the button is hidden. It comes back if the domain drifts. 2. **The deployment doesn't have guided setup enabled.** Self-hosted installs need DoDomain credentials — see the callout at the top of this page. 3. **The record table is collapsed.** The button lives in the record table header; expand **DNS Configuration Required** / **View DNS Records** to see it. ### "A guided setup session was just started for this domain" [#a-guided-setup-session-was-just-started-for-this-domain] Each domain can only start one session per minute. This is a double-click guard, not a limit on how many times you may use the feature — wait a moment and press the button again. ### The sheet didn't open, or opened in a new tab [#the-sheet-didnt-open-or-opened-in-a-new-tab] The connect flow is an embedded frame, and content blockers, corporate proxies and strict browser settings can prevent it from mounting. Sendly detects that and opens the same flow as a full page in a new tab. The flow is identical; finish it there. ### Guided setup finished but the domain still says Pending [#guided-setup-finished-but-the-domain-still-says-pending] Publishing a record and a receiver *seeing* it are different events. DNS changes can take up to 48 hours to propagate, and SES will not flip the domain to **Verified** until it reads the DKIM records itself. Use the refresh button on the domain row to re-check, and see [records not verifying](/guides/verifying-domains#records-not-verifying) if it stays pending past that. ### "Guided setup did not finish for yourdomain.com" [#guided-setup-did-not-finish-for-yourdomaincom] The flow was started but ended without publishing. Nothing is broken and nothing was half-written that you need to undo — start it again, or add the records by hand from the table below the message. The full record set, the manual path, and what each record does Inbound MX setup for triggering workflows from incoming mail --- # Receiving emails (/guides/receiving-emails) Sendly can receive emails sent to your verified domain and turn them into `email.received` events. This allows you to build automated workflows that respond to inbound emails, such as support ticket systems, auto-responders, or email-based integrations. ## How it works [#how-it-works] When someone sends an email to your verified domain (e.g., `support@yourdomain.com` or `hello@yourdomain.com`), Sendly will: 1. Receive the email through AWS SES 2. Automatically create or update a contact for the sender 3. Trigger an `email.received` event that can start workflows 4. Make the email metadata available to your workflow steps The sender is automatically added to your contacts as a subscribed contact, allowing you to respond using Sendly's email sending capabilities. ## Setting up inbound email [#setting-up-inbound-email]
### Verify your domain [#verify-your-domain] Before you can receive emails, your domain must be verified in Sendly. Follow the [verifying domains](/guides/verifying-domains) guide to set up the required DKIM, SPF, and MX records for sending — or use [guided DNS setup](/guides/guided-dns-setup) to have Sendly publish them for you. ### Add the inbound MX record [#add-the-inbound-mx-record] In your project settings, navigate to the **Domains** tab and expand your verified domain. You'll see an optional "Inbound Email" section with an MX record configuration: - **Type**: MX - **Name**: `yourdomain.com` (your root domain) - **Value**: `10 inbound-smtp.eu-north-1.amazonaws.com` Add this MX record to your domain's DNS settings. The priority value `10` ensures that inbound emails are routed to AWS SES for processing. If you're already using MX records for another email service (like Google Workspace or Microsoft 365), adding this MX record may conflict. You can only have one primary email receiver per domain. Consider using a subdomain (e.g., `mail.yourdomain.com`) if you need to maintain both services. ### Wait for DNS propagation [#wait-for-dns-propagation] DNS changes can take anywhere from a few minutes to 48 hours to fully propagate. You can verify the MX record is set correctly using: ```bash dig MX yourdomain.com ``` You should see the AWS SES inbound endpoint in the response.
## Creating workflows with email.received [#creating-workflows-with-emailreceived] Once your MX record is configured, you can create workflows that respond to incoming emails. ### Event trigger [#event-trigger] Create a new workflow and use `email.received` as the trigger event. This workflow will run every time an email is received at your domain. ### Available event data [#available-event-data] The `email.received` event includes the following data that you can use in your workflow steps: | Field | Type | Description | | ---------------------- | -------- | ------------------------------------------------- | | `sesMessageId` | string | Unique identifier for the received message | | `from` | string | Email address of the sender | | `fromHeader` | string | Full "From" header including display name | | `to` | string | Primary recipient email address | | `subject` | string | Email subject line | | `timestamp` | string | ISO 8601 timestamp when the email was received | | `recipients` | string[] | All recipient email addresses | | `hasContent` | boolean | Whether the email body was captured | | `body` | string | HTML body of the email (or plain text if no HTML) | | `spamVerdict` | string | Spam check result (e.g., "PASS", "FAIL") | | `virusVerdict` | string | Virus scan result (e.g., "PASS", "FAIL") | | `spfVerdict` | string | SPF authentication result | | `dkimVerdict` | string | DKIM authentication result | | `dmarcVerdict` | string | DMARC authentication result | | `processingTimeMillis` | number | Time taken to process the email | You can access these fields in your workflow using variable syntax, for example: `{{event.subject}}`, `{{event.from}}`, or `{{event.body}}`. ### Example: Auto-reply workflow [#example-auto-reply-workflow] Here's a simple workflow that sends an automatic reply when an email is received at `support@yourdomain.com`: 1. **Trigger**: `email.received` 2. **Condition**: Check if `{{event.to}}` equals `support@yourdomain.com` 3. **Send Email**: - **To**: `{{event.from}}` - **Subject**: `Re: {{event.subject}}` - **Body**: `Thank you for your message. We received: "{{event.body}}". We'll get back to you soon!` This workflow reads the incoming email body and includes it in the auto-reply response. ### Example: Forward to webhook [#example-forward-to-webhook] For more advanced processing (like ticket creation or AI analysis), you can forward the email content to your own API: 1. **Trigger**: `email.received` 2. **Webhook**: - **URL**: `https://api.example.com/support/tickets` - **Method**: `POST` - **Body**: ```json { "from": "{{event.from}}", "subject": "{{event.subject}}", "body": "{{event.body}}", "timestamp": "{{event.timestamp}}" } ``` Your backend receives the full email content and can process it (create a ticket, run AI analysis, etc.). ## Multi-project domains [#multi-project-domains] If you have verified the same domain in multiple projects, incoming emails will be processed for **all projects** that have the domain verified. Each project will: - Create/update the sender as a contact in that project - Trigger the `email.received` event in that project - Run any workflows configured for that event This allows you to segment inbound email handling across different projects if needed. ## Limitations [#limitations] - **Catch-all addresses**: Sendly receives emails sent to any address at your verified domain (e.g., `anything@yourdomain.com`). You can use workflow conditions to route emails based on the `to` field. - **Attachments**: Email attachments are not currently captured or stored. - **Email size**: AWS SES has a maximum message size limit of 40 MB for inbound emails. ## Security considerations [#security-considerations] Sendly captures several security verdicts for each incoming email: - **SPF (Sender Policy Framework)**: Verifies the sender's mail server is authorized - **DKIM (DomainKeys Identified Mail)**: Validates the email hasn't been tampered with - **DMARC (Domain-based Message Authentication)**: Combines SPF and DKIM for additional validation - **Spam verdict**: AWS SES's spam detection result - **Virus verdict**: AWS SES's virus scanning result You can use these verdicts in workflow conditions to automatically filter or quarantine suspicious emails before processing them. ## Troubleshooting [#troubleshooting] ### Emails not being received [#emails-not-being-received] 1. **Check DNS propagation**: Verify the MX record is correctly set using `dig MX yourdomain.com` 2. **Verify domain**: Ensure your domain is fully verified in Sendly (all DKIM, SPF, and MX records for sending) 3. **Check workflow**: Create a simple test workflow with just an `email.received` trigger and a webhook to verify events are being generated 4. **Check sender**: Try sending from a different email provider as some may cache DNS records ### Duplicate events [#duplicate-events] If you have the same domain verified in multiple projects, you will receive duplicate `email.received` events (one per project). This is expected behavior. Use project-specific workflows to handle this. ### Security verdicts failing [#security-verdicts-failing] If incoming emails consistently show failing security verdicts: - **SPF failures**: The sender's domain may not have SPF configured correctly - **DKIM failures**: The sender's domain may not have DKIM configured, or the email was forwarded/modified in transit - **DMARC failures**: The sender fails both SPF and DKIM checks These are issues with the sender's configuration, not your Sendly setup. You can choose to process these emails anyway or filter them using workflow conditions. --- # Tracking (/guides/tracking) Sendly provides built-in tracking for email opens and link clicks. This allows you to monitor the engagement of your emails and gain insights into how your contacts interact with your content. ## Open tracking [#open-tracking] When open tracking is enabled, Sendly includes a small, invisible tracking pixel in your emails. When a contact opens the email, the pixel is loaded, and Sendly records the open event. ### Considerations [#considerations] - Open tracking relies on the loading of images in the email client. If a contact has images disabled, the open event may not be recorded. - Some email clients may pre-load images, which can result in false open events. ## Click tracking [#click-tracking] Click tracking is enabled by default for all emails sent through Sendly. When a contact clicks on a link in the email, Sendly records the click event and tracks which link was clicked. ### Considerations [#considerations-1] - Click tracking works by rewriting the URLs in your email to point to Sendly's tracking servers - Some email clients or security software may block tracking links, which can result in missed click events ## Configuration [#configuration] There are three levels of configuration for tracking: | Level | Description | |-------|-------------| | Enabled | Tracking is enabled for all emails | | Disabled | Tracking is disabled for all emails | | Marketing only | Tracking is enabled only for marketing emails (templates and campaigns) | --- # API Keys (/guides/api-keys) API keys authenticate requests made to Sendly's API. They come in two tiers: a sending-only publishable key (`pk_…`), which can send email and manage list subscriptions but cannot read your data or track events, and a secret key (`sk_…`), which can do everything you allow it to. ## Public Key [#public-key] The public (publishable) key, `pk_…`, is a sending-only key. It holds one permission, `emails:send`, and is accepted only where a visitor's browser may reasonably trigger the action: - sending email: [`POST /api/v1/emails`](/api-reference/emails/sendEmail), `POST /api/emails`, `POST /api/emails/batch`, and the compatibility send endpoints; - list sign-ups: `POST /api/lists/{id}/subscribe` and `POST /api/lists/{id}/unsubscribe`. Everywhere else it is refused with `403 INSUFFICIENT_PERMISSIONS`. That includes [`/api/track`](/api-reference/events/trackEvent) and `/api/v1/events`: a public key **cannot track events**, because events drive segments and workflow triggers and writing them is not sending. Track events with a secret key from your server. A public key is also refused by the MCP server, and its rate limit is tighter (5 requests per second per key, against 10 for a secret key). A public key can still send real email as your project, so anyone who copies it can send as you, at that rate limit. Rotate it if it leaks. ## Secret Key [#secret-key] The secret API key can be used with all other endpoints in Sendly's API. This key should be kept confidential and not exposed in client-side applications. If this key is compromised, a malicious actor could read and modify your project data, send emails, and perform other actions on your behalf. Sendly's MCP server at `/api/mcp` accepts a secret key on the `Authorization` header as well as an OAuth token, and for a headless or CI agent the key is the simpler of the two — there is no browser flow. **The key's own permissions are exactly what the agent may do**, so tick them deliberately when you create it: a key granted `emails:send` gives the agent a tool that puts mail in real inboxes. Sending-only `pk_…` keys are refused there. A key created before Sendly had per-capability permissions is not given the irreversible tools at all — create a new key and choose what it may do. See the [MCP guide](/guides/mcp). An agent granted `api-keys:read` can see which keys exist and what each may do. One granted `api-keys:write` can create a key, rotate a key's secret, and permanently revoke a key. **The secret is never returned to the agent.** Creating or rotating a key through an agent gives it only the key's name, its last four characters, and a one-time link; opening that link requires your signed-in Sendly session, so the agent that asked for the key cannot open it. The link works once and expires after five minutes. A key an agent creates can only carry permissions the agent itself already has. Asking for more is refused outright rather than quietly trimmed, so an agent cannot use `api-keys:write` to manufacture a permission you never granted it. All of this needs an agent connected over **OAuth**. Key management is the one area an agent connected **with a secret key** cannot touch at all: every API-key route identifies a project admin from the signed-in user, and a key carries no user, so those tools are not offered to a key connection whatever permissions it holds. Listing, creating, rotating and revoking are all OAuth-only. ## Permissions older keys do not have [#permissions-older-keys-do-not-have] Two permissions are **opt-in only**: `mailbox-conversations:read` (list a mailbox's conversations and read their messages and attachments) and `mailbox-conversations:reply` (reply to a conversation from the mailbox's own address). The mail a hosted mailbox receives is written by people outside your project, so reading it and answering it are decisions of their own, separate from `mailboxes:read` (a mailbox's settings) and from `mailboxes:send` (starting a new message). **No key created before them has either one.** A key created before they existed — including a legacy full-access key — does not gain them. A new full key starts with every permission checked, these two included; untick them under **Read your data** and **Delete, publish or send** in the API-key dialog, or on the consent screen for an app connecting over OAuth. They are separate from each other, so a key can read a support inbox without being able to answer anyone in it. A request without the right permission is refused with `403 SCOPE_MISSING`, whichever credential — key or OAuth connection — made it. See [List a mailbox's conversations](/api-reference/mailboxes/listMailboxConversations) and [Reply to a conversation](/api-reference/mailboxes/replyToMailboxConversation). ## Live and test keys [#live-and-test-keys] Every key is minted in one of two modes, chosen when you create it and fixed for the life of the key. The mode is orthogonal to the key's permissions: a test key can hold every permission and still be unable to reach a customer. | Mode | Token | What it can send | | ---- | ----- | ---------------- | | Live | `sk_…` / `pk_…` | Real email from your verified domains, to anyone. | | Test | `sk_test_…` / `pk_test_…` | Only from your project's sandbox address (`@sendly.now`), and only to the verified email of the project's owner. | The prefix keeps its existing meaning — `sk_` is a secret key, `pk_` is a publishable one — and the mode is appended after it, so every key issued before test mode existed still works unchanged and every secret scanner still fires on the same two prefixes. A test send is a **real send**. It goes down the same pipeline, through SES, against the same rate limits and the same sandbox daily cap, and it appears in your logs and in `GET /api/emails` like any other message. The only differences are where it is allowed to go and that the message is marked `sentInTestMode`, so you can tell rehearsal traffic apart afterwards. Sendly decides a key's mode from the key itself, never from the string you send. Retyping a live token with `test_` in it does not make it a test key — it is still the live key it has always been, and it will send real email. A test key is refused in two different ways, so a `catch` can tell them apart: - `403 TEST_KEY_SANDBOX_ONLY` when the `from` address is anything other than the project's sandbox address; - `403 FORBIDDEN` when the `from` address is the sandbox address but a recipient (`to`, `cc` or `bcc`) is not the owner's verified email. The sandbox also has a daily send cap; past it the send is refused with `429`. - `403 SANDBOX_ALLOWANCE_EXHAUSTED` (`quota_exhausted` on `/api/v1`) when a project with no verified domain and no subscription has used its 20 free test emails. Verify a domain to lift it; see [verifying domains](/guides/verifying-domains#free-test-emails-before-you-verify). Use a test key for CI, for a staging deploy, and for the first run of anything that sends in a loop. A test key that is wired up wrong fails loudly — it is refused with `403 TEST_KEY_SANDBOX_ONLY` the moment it tries to send from a verified domain, before any message is created — which is the point: you find out from an error, not from a customer. **Campaigns are refused outright.** `POST /v1/campaigns/{id}/send` answers the same `403 TEST_KEY_SANDBOX_ONLY` for a test key, whether you are sending now or scheduling for later, and no campaign is started. There is no sandbox form of a campaign: a campaign always goes to its real audience from a verified domain, so "confined to the sandbox" has only one meaning here. Rehearse a campaign with **Send test**, which delivers one message and only ever to a member of the project, and use a live key to send it for real. ## Regenerating API Keys [#regenerating-api-keys] If you believe a key has been compromised, you can regenerate — rotate — it from the project's API keys settings. Rotating replaces **that one key's secret**. The key keeps its id, its name and its permissions, and every other key on the project is untouched: keys are separate credentials, so rotating your secret key does nothing to your public key or to any other secret key. The previous secret stops authenticating **immediately** — on the very next request, not after a grace period — because rotating replaces the identifier Sendly looks the key up by. Anything still deployed with the old secret starts failing at once, so have the replacement ready to deploy before you rotate. There is no way to undo a rotation: the old secret was only ever stored as a hash, so nobody can bring it back. The new secret is shown once, in your browser, the same way it is at creation — copy it then. If an agent performed the rotation, it receives the one-time link rather than the secret, and only you can open it. A key that has already been revoked cannot be rotated; create a new one instead. --- # Localization (/guides/localization) Localization in Sendly allows you to configure the language of the unsubscribe footer and contact-facing pages (subscribe, unsubscribe, manage) to better suit your audience. ## Configuring Localization [#configuring-localization] You can set the default language for your project in the project settings. ## Overriding language per contact [#overriding-language-per-contact] You can override the default language for individual contacts by setting the `locale` field in the contact data. This field should contain a valid [ISO 639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code (e.g., 'en' for English, 'fr' for French, 'es' for Spanish). When sending emails, Sendly will use the contact's specified language if available; otherwise, it will fall back to the project's default language. --- # Template Syntax (/guides/template-syntax) Every email Sendly sends is rendered from a template: a subject and a body with placeholders in them. The same renderer runs for transactional sends, campaigns and workflow steps, and the same one runs the preview in the editor, so what you see there is what the recipient gets. ## The one rule [#the-one-rule] **Values are escaped. Markup is not.** The template body is yours: you wrote it, and Sendly renders your `` as a table. A *value* — anything that arrives from a contact record, a custom field, or the `data` you pass to the send API — is somebody else's text, and it is HTML-escaped before it lands in the body. ``` Template:

Hello {{firstName}}

Value: firstName = Rendered:

Hello <script>alert(1)</script>

``` That holds everywhere: inside a conditional, inside a loop, and inside a snippet pulled into a loop. There is no "raw" or "unescaped" form of a placeholder, and no helper that turns escaping off. `{{{firstName}}}` is not raw output — it is read as a variable named `{firstName`, which never exists, so it renders as nothing. Subjects are not HTML, so they are treated differently: values in a subject have line breaks and control characters stripped (which is what stops a value from injecting a `Bcc:` header), and they are not entity-encoded. ## Variables [#variables] ``` {{email}} A top-level field {{customFields.plan}} A nested path {{firstName ?? there}} A default when the value is missing or empty ``` A variable that resolves to nothing renders as an empty string. The `?? default` text is yours, not a value, so it is not escaped — write markup in it if you want to. An array renders as `
  • ` items in a body and as a comma-separated list in a subject. Use `{{#each}}` below when you want control over the markup. ## Conditionals [#conditionals] ``` {{#if plan}}You are on the {{plan}} plan.{{else}}Pick a plan when you are ready.{{/if}} {{#unless unsubscribed}}Manage your preferences{{/unless}} ``` Empty means absent: an empty string, an empty list, an empty object, `0` and `false` all take the `{{else}}` branch. The branch that is not taken renders nothing at all. ## Loops [#loops] ``` {{#each items}}
  • {{else}} {{/each}} ``` Inside the loop: - `{{this}}` is the current item, for a list of plain strings or numbers. - `{{@index}}` is the position, starting at `0`. - A field name (`{{name}}`) reads the field of the current item, and falls back to the outer contact record when the item has no such field — so `{{firstName}}` still works inside a loop over line items. - `{{this.field}}` reads the item's field only, when you want to be explicit. `{{else}}` inside `{{#each}}` renders when the list is empty or missing. ## Snippets [#snippets] A snippet is a fragment of template markup stored on your project and reused by name. Create one from the Insert Snippet control in the template editor, or through the API (`POST /api/snippets`). Include it with `{{> name}}`: ```

    Your order is on its way.

    {{> signature}} {{> legal_footer}} ``` Variables inside a snippet resolve against the same contact record the surrounding template uses, and they are escaped the same way. A snippet may include another snippet, and may contain conditionals and loops. The name in `{{> name}}` is always a literal identifier — it must start with a letter and contain only letters, digits, hyphen and underscore. **There is no way to choose a snippet from a value.** `{{> {{whichever}}}}` does not select the snippet a contact field names; it is rejected. That is deliberate: a template author picks what gets included, never the data. A snippet that does not exist renders as an empty string, exactly like a variable that does not exist. Deleting a snippet therefore leaves templates that include it still sending — with a gap where it was. ## Comments [#comments] ``` {{! This note never reaches the recipient. }} ``` ## Limits [#limits] A template and the snippets it pulls in are rendered on every send, so a render is bounded. These are the exact limits: | Limit | Value | | --------------------------------------------------------- | ------- | | Nested blocks and snippet includes (one shared depth) | 10 | | Iterations rendered by a single `{{#each}}` | 1000 | | Characters of rendered output, snippets included | 262144 | | Snippet includes performed by one render | 100 | Exceeding a limit fails the render rather than sending a half-built message; so does an unclosed `{{#if}}` or `{{#each}}`, or an unknown block helper. The editor preview reports which one, so you can see the mistake while you are still writing. Two snippets that include each other are stopped by the depth limit rather than looping forever. --- # Webhooks (/guides/webhooks) Sendly can send real-time HTTP requests to your application when specific events occur, such as email bounces, spam complaints, or custom events. There are two ways to receive them, and they are different things: - **Webhook subscriptions** (`POST /api/webhooks`, or **Settings → Webhooks** in Sendly) deliver a fixed set of ten events to your endpoint. Every delivery is **signed**, retried, and verifiable. Start with [Webhook subscriptions](#webhook-subscriptions-and-signature-verification) below. - **The workflow Webhook step** forwards any event a workflow can trigger on, including your own custom events. Those requests are **not signed**; authenticate them with a custom header you configure on the step. The rest of this page, from [How it works](#how-it-works) down, covers this path. ## Webhook subscriptions and signature verification [#webhook-subscriptions-and-signature-verification] ### Events you can subscribe to [#events-you-can-subscribe-to] `eventTypes` on `POST /api/webhooks` accepts exactly these ten names. Anything else is a 400. Each event name links to its API reference page, which shows the exact payload. | Event | When it fires | | ----------------------- | ----------------------------------------------------------- | | [`email.sent`](/api-reference/webhooks/webhook_email_sent) | The message was handed to the sending infrastructure | | [`email.delivered`](/api-reference/webhooks/webhook_email_delivered) | The recipient's server accepted it | | [`email.opened`](/api-reference/webhooks/webhook_email_opened) | The message was opened | | [`email.clicked`](/api-reference/webhooks/webhook_email_clicked) | A link in the message was clicked | | [`email.bounced`](/api-reference/webhooks/webhook_email_bounced) | The message hard-bounced (a soft bounce does not fire this) | | [`email.complained`](/api-reference/webhooks/webhook_email_complained) | The recipient marked it as spam | | [`email.failed`](/api-reference/webhooks/webhook_email_failed) | The send failed before or at handoff, or the mail server gave up on it afterwards (it expired in the queue, or was finally refused for a reason that says nothing against the address) | | [`contact.created`](/api-reference/webhooks/webhook_contact_created) | A contact was created, by any route including an import | | [`contact.unsubscribed`](/api-reference/webhooks/webhook_contact_unsubscribed) | A contact's status changed to unsubscribed | | [`contacts.bulk_created`](/api-reference/webhooks/webhook_contacts_bulk_created) | A bulk import finished creating contacts | These are not the workflow trigger names further down this page (`email.delivery`, `email.open`, `email.click`, `email.bounce`, `email.complaint`, `contact.subscribed`). A subscription to a workflow name is rejected; a workflow trigger on a subscription name never fires. [Event vocabularies](/integrations/event-vocabulary) sets the two lists side by side. ### What a delivery looks like [#what-a-delivery-looks-like] Each delivery is an HTTP `POST` with a JSON body and these headers: | Header | Value | | -------------------- | ------------------------------------------------------------------------------------------------------------ | | `Content-Type` | `application/json` | | `User-Agent` | `Sendly-Webhook/1.0` | | `X-Sendly-Event` | The event name, for example `email.sent` | | `X-Sendly-Timestamp` | Unix time in **milliseconds**, as a decimal string | | `X-Sendly-Signature` | Lowercase hex HMAC-SHA256, 64 characters, with no `sha256=` prefix | | `webhook-id` | A message id, stable across every retry of the same event. Dedupe on it. | | `webhook-timestamp` | Unix time in **seconds**, as a decimal string | | `webhook-signature` | One or more space-separated `v1,` signatures ([Standard Webhooks](https://www.standardwebhooks.com)) | The body is an envelope. `timestamp` repeats `X-Sendly-Timestamp`, and `data` depends on the event: ```json { "event": "email.sent", "data": { "emailId": "e1" }, "timestamp": "1700000000000" } ``` Every delivery carries **two independent signatures**, so use whichever your tooling supports. Both are computed over the **raw request body**, byte for byte. Never parse and re-serialise the JSON first, and never verify against a framework's re-formatted copy. ### Scheme 1: `X-Sendly-Signature` (what the SDKs verify) [#scheme-1-x-sendly-signature-what-the-sdks-verify] ```text signed_payload = X-Sendly-Timestamp + "." + raw_body signature = lowercase_hex( HMAC_SHA256( key = secret, message = signed_payload ) ) ``` - The separator is a single ASCII dot, with no spaces and no newline. - The timestamp is the header's decimal string exactly as sent (milliseconds), not re-formatted. - The key is the **secret string as stored**, UTF-8 encoded. For a secret of the form `whsec_...` this means the whole string including the `whsec_` prefix. Do **not** base64-decode it in this scheme. - Compare in constant time. Reject any `X-Sendly-Timestamp` that is not all digits. ### Scheme 2: `webhook-signature` (Standard Webhooks) [#scheme-2-webhook-signature-standard-webhooks] ```text signed_payload = webhook-id + "." + webhook-timestamp + "." + raw_body signature = "v1," + base64( HMAC_SHA256( key, signed_payload ) ) ``` - `webhook-timestamp` is in **seconds** here. - `key` is the base64-**decoded** remainder when the secret starts with `whsec_`. A secret without that prefix (every secret minted before rotation shipped) is used as its raw UTF-8 bytes. - The header may hold **several** signatures separated by single spaces. Accept the request if **any** of them matches. This is how key rotation stays seamless; see below. - Off-the-shelf Standard Webhooks libraries verify this header with no Sendly-specific code. ### Timestamp tolerance [#timestamp-tolerance] Reject a delivery whose timestamp is more than **5 minutes** from your clock, in either direction. The timestamp is inside the signed payload, so an attacker cannot move a captured delivery forward in time; the tolerance is what makes a captured request useless a few minutes later (a replay). Five minutes absorbs ordinary clock skew. Keep your server clock on NTP. Every retry is re-signed with a fresh timestamp, so a late retry is never rejected for age. Skip the freshness check only when replaying stored deliveries, for example in a test. ### Rotating the secret [#rotating-the-secret] `POST /api/webhooks/{id}/rotate-secret` (or `rotateSecret` in the SDK) returns the new secret once. The previous secret keeps working for **24 hours**, and only **one** previous secret is live at a time; rotating twice inside the window drops the oldest. During those 24 hours: - `webhook-signature` carries **two** signatures, the new secret's first and the previous secret's second. A verifier holding either secret accepts the request. - `X-Sendly-Signature` is signed with the **new** secret only. A verifier still holding the old secret fails this header at once. So for zero-downtime rotation, verify `webhook-signature` and try every secret you hold. If you verify only `X-Sendly-Signature` (as the SDKs do), deploy the new secret promptly after rotating. When a signature check fails, answer with a **5xx** (or let the error propagate) so Sendly retries the delivery. A **4xx is never retried**: it counts toward the 20-failure auto-disable below, and the event can then only be recovered by replaying it (`POST /api/webhooks/{id}/replay-failed`, which covers the last 24 hours by default). ### A test vector [#a-test-vector] Use this to check an implementation in any language without a live send. The expected values were produced by Sendly's own signing code. | Input | Value | | -------------------- | ---------------------------------------------------------------------------- | | Secret | `whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYX` | | `X-Sendly-Timestamp` | `1700000000000` | | `webhook-id` | `msg_2c9f8e1a4b7d4c3e` | | `webhook-timestamp` | `1700000000` | | Raw body | `{"event":"email.sent","data":{"emailId":"e1"},"timestamp":"1700000000000"}` | | Expected header | Value | | -------------------- | ------------------------------------------------------------------ | | `X-Sendly-Signature` | `e8f3ca5c77d88269b09281a87b5fc48618b3be252093374345312315a92be620` | | `webhook-signature` | `v1,KXrjybsdQ1Rrr93ZXptngyvnG2kWwlMzUKH7cmozDTM=` | The timestamp is in 2023, so a verifier with the 5-minute tolerance rejects it as stale. Run the vector with the freshness check disabled, or with your clock pinned to that instant. ### Verifying a delivery [#verifying-a-delivery] `sendly-sdk` verifies the `X-Sendly-Signature` scheme and throws on a bad signature or a stale timestamp. Pass the raw body, not the parsed one. ```ts import express from 'express'; import { constructEvent } from 'sendly-sdk'; const app = express(); app.post('/webhooks/sendly', express.raw({ type: 'application/json' }), (req, res) => { try { const event = constructEvent( req.body, // Buffer: the raw bytes req.headers['x-sendly-signature'] as string, req.headers['x-sendly-timestamp'] as string, process.env.SENDLY_WEBHOOK_SECRET!, ); // event.event, event.data res.sendStatus(200); } catch { // A 5xx is retried; a 4xx never is. Answer 5xx on a failed check so a stale secret does not lose the event. res.sendStatus(500); } }); ``` Standard library only. `verify_legacy` checks `X-Sendly-Signature`; `verify_standard` checks `webhook-signature` against every secret you hold, which is what you want during a rotation. ```python import base64 import hashlib import hmac import time TOLERANCE_MS = 5 * 60 * 1000 def verify_legacy(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool: if not (timestamp.isascii() and timestamp.isdigit()): return False if abs(time.time() * 1000 - int(timestamp)) > TOLERANCE_MS: return False expected = hmac.new( secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, signature) def verify_standard(raw_body: bytes, msg_id: str, timestamp_s: str, header: str, secrets: list[str]) -> bool: if not (timestamp_s.isascii() and timestamp_s.isdigit()): return False if abs(time.time() - int(timestamp_s)) > TOLERANCE_MS / 1000: return False signed = f"{msg_id}.{timestamp_s}.".encode() + raw_body candidates = [p.split(",", 1)[1] for p in header.split(" ") if p.startswith("v1,")] for secret in secrets: key = base64.b64decode(secret[len("whsec_"):]) if secret.startswith("whsec_") else secret.encode() expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() if any(hmac.compare_digest(expected, c) for c in candidates): return True return False ``` In a Flask handler, call `request.get_data()` for `raw_body`; do not use `request.json`. ### Delivery, retries and failures [#delivery-retries-and-failures] - A `2xx` response is success. Any other status, a timeout (10 seconds) or a connection error is a failed attempt. - A `4xx` is treated as a rejection and is **not** retried. Anything else is retried up to 8 more times, after roughly 30 seconds, 2 minutes, 10 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, each with up to 20% jitter. - After 20 consecutive failed deliveries the endpoint is switched off, with warnings to the project's members along the way. A single success resets the count. - Delivery is at-least-once. Dedupe on `webhook-id`, which does not change between retries. ## How it works [#how-it-works] Webhooks in Sendly are powered by the workflow system. The basic flow is: 1. An event occurs in Sendly (e.g. an email bounces, a contact subscribes, or a custom event is tracked) 2. A workflow is triggered by that event 3. The workflow executes a **Webhook** step, sending an HTTP request to your URL with relevant data This means you can receive notifications for any event Sendly tracks, including both system events and your own custom events. ## Internal events [#internal-events] Sendly automatically tracks a set of internal events that you can use as workflow triggers. These events cannot be manually tracked via the API — they are generated by the system. The names below are what a **workflow** triggers on. The `eventTypes` field on `POST /api/webhooks` takes a different, shorter list — `email.delivered` rather than `email.delivery`, `email.bounced` rather than `email.bounce`. Both lists are set out side by side in [Event vocabularies](/integrations/event-vocabulary). ### Email events [#email-events] | Event | Description | | ----------------- | -------------------------------------------------------------------------------------------------------- | | `email.sent` | An email was successfully sent | | `email.delivery` | An email was delivered to the recipient | | `email.open` | A contact opened an email for the first time | | `email.click` | A contact clicked a link in an email for the first time | | `email.bounce` | An email bounced (hard or soft bounce) | | `email.complaint` | A contact marked an email as spam | | `email.received` | An email was received at your verified domain (requires [inbound email setup](/guides/receiving-emails)) | ### Contact events [#contact-events] | Event | Description | | ---------------------- | ------------------------------------------------------- | | `contact.subscribed` | A contact's subscription status changed to subscribed | | `contact.unsubscribed` | A contact's subscription status changed to unsubscribed | ### Segment events [#segment-events] | Event | Description | | ---------------------- | --------------------------- | | `segment..entry` | A contact entered a segment | | `segment..exit` | A contact exited a segment | Segment events use a slugified version of the segment name. For example, a segment called "VIP Users" would produce the events `segment.vip-users.entry` and `segment.vip-users.exit`. ## Setting up a webhook [#setting-up-a-webhook]
    ### Create the workflow [#create-the-workflow] Navigate to the **Workflows** section in Sendly and create a new workflow. Choose the event you want to listen for as the trigger. For example, to receive notifications when an email bounces, use `email.bounce` as the trigger event. ### Add a Webhook step [#add-a-webhook-step] After the trigger, add a **Webhook** step and configure it: - **URL**: The endpoint on your server that will receive the webhook (e.g. `https://api.example.com/webhooks/sendly`) - **Method**: The HTTP method to use. Defaults to `POST`, which is recommended for most use cases. - **Headers** (optional): Custom headers to include in the request, provided as JSON. This is useful for authentication. ```json { "Authorization": "Bearer your-secret-token" } ``` ### Enable the workflow [#enable-the-workflow] Once configured, enable the workflow. It will start sending webhook requests whenever the trigger event occurs.
    ## Webhook payload [#webhook-payload] When using the default payload (no custom body configured), Sendly sends a JSON request with the following structure: ```json { "contact": { "email": "user@example.com", "subscribed": true, "data": { "name": "John", "plan": "pro" } }, "workflow": { "id": "wf_abc123", "name": "Bounce Notifications" }, "execution": { "id": "exec_xyz789", "startedAt": "2025-01-15T10:30:00.000Z" }, "event": { "subject": "Welcome to Sendly", "from": "hello@example.com", "fromName": "Sendly Team", "sesMessageId": "ses-message-id", "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "templateId": null, "campaignId": "camp_abc123", "sourceType": "CAMPAIGN", "bounceType": "Permanent", "bouncedAt": "2025-01-15T10:30:00.000Z" } } ``` The `event` field contains the data associated with the event that triggered the workflow. The exact contents depend on the event type. ### Event data by type [#event-data-by-type] #### Email events [#email-events-1] Most email events share a common set of base fields: | Field | Description | | ------------ | ------------------------------------------------------------------------------------------------------ | | `subject` | The email subject line | | `from` | The sender email address | | `fromName` | The sender display name | | `sesMessageId` | The AWS SES message ID (for correlating with SES events) | | `emailId` | The Sendly email record ID (returned from `POST /api/emails`, for correlating webhooks with API responses) | | `templateId` | The template ID, if the email was sent using a template (otherwise `null`) | | `campaignId` | The campaign ID, if the email was part of a campaign (otherwise `null`) | | `sourceType` | How the email was triggered: `TRANSACTIONAL`, `CAMPAIGN`, `WORKFLOW`, or `INBOUND` | In addition to these base fields, each event includes the following event-specific fields: ```json { "subject": "Welcome to Sendly", "from": "hello@example.com", "fromName": "Sendly Team", "sesMessageId": "ses-message-id", "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "templateId": null, "campaignId": null, "sourceType": "TRANSACTIONAL", "sentAt": "2025-01-15T10:30:00.000Z" } ``` | Field | Description | | -------- | ----------------------- | | `sentAt` | When the email was sent | ```json { "subject": "Welcome to Sendly", "from": "hello@example.com", "fromName": "Sendly Team", "sesMessageId": "ses-message-id", "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "templateId": null, "campaignId": "camp_abc123", "sourceType": "CAMPAIGN", "deliveredAt": "2025-01-15T10:30:05.000Z" } ``` | Field | Description | | ------------- | ---------------------------- | | `deliveredAt` | When the email was delivered | ```json { "subject": "Welcome to Sendly", "from": "hello@example.com", "fromName": "Sendly Team", "sesMessageId": "ses-message-id", "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "templateId": null, "campaignId": null, "sourceType": "TRANSACTIONAL", "openedAt": "2025-01-15T11:00:00.000Z", "opens": 1, "isFirstOpen": true } ``` | Field | Description | | ------------- | ------------------------------------------------------------- | | `openedAt` | When the email was first opened | | `opens` | Total number of times this email has been opened | | `isFirstOpen` | `true` if this is the first time the contact opened the email | ```json { "subject": "Welcome to Sendly", "from": "hello@example.com", "fromName": "Sendly Team", "sesMessageId": "ses-message-id", "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "templateId": null, "campaignId": null, "sourceType": "TRANSACTIONAL", "link": "https://example.com/pricing", "clickedAt": "2025-01-15T11:05:00.000Z", "clicks": 1, "isFirstClick": true } ``` | Field | Description | | -------------- | ----------------------------------------------------------------- | | `link` | The URL that was clicked | | `clickedAt` | When the first click occurred | | `clicks` | Total number of times links in this email have been clicked | | `isFirstClick` | `true` if this is the first click from this contact on this email | Permanent bounce: ```json { "subject": "Welcome to Sendly", "from": "hello@example.com", "fromName": "Sendly Team", "sesMessageId": "ses-message-id", "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "templateId": null, "campaignId": null, "sourceType": "TRANSACTIONAL", "bounceType": "Permanent", "bounceSubType": "NoEmail", "bounceDiagnosticCode": "smtp; 550 5.1.1 <[address removed]>: Recipient address rejected: User unknown", "bounceStatusCode": "5.1.1", "bouncedAt": "2025-01-15T10:31:00.000Z" } ``` Transient (soft) bounce: ```json { "subject": "Welcome to Sendly", "from": "hello@example.com", "fromName": "Sendly Team", "sesMessageId": "ses-message-id", "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "templateId": null, "campaignId": null, "sourceType": "TRANSACTIONAL", "bounceType": "Transient", "bounceSubType": "MailboxFull", "bounceDiagnosticCode": null, "bounceStatusCode": "4.2.2", "transientBounce": true } ``` | Field | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `bounceType` | `Permanent` (hard bounce) or `Transient` (soft bounce, e.g. mailbox full or out-of-office) | | `bounceSubType` | Why SES classed it so: `NoEmail` (the address does not exist), `Suppressed` or `OnAccountSuppressionList` (a suppression list refused the send; the list is shared across Sendly, so this says the address is suppressed and never whose message put it there), `MailboxFull`, `General`, and others. `null` when SES gave none | | `bounceDiagnosticCode` | The receiving server's own reply, for a person to read. Email addresses in it are replaced with `[address removed]`, and it is cut at 500 characters. `null` when SES gave none | | `bounceStatusCode` | The RFC 3463 status code of the bounce, e.g. `5.1.1`. `5.1.x` is an address problem on the recipient's side; `5.7.x` is a policy refusal on the sending side. `null` when SES gave none | | `bouncedAt` | When the bounce occurred (permanent bounces only) | | `transientBounce` | `true` for soft bounces — these do not count toward bounce rate and the contact stays subscribed. A soft bounce the mail server will not retry also fails the email: your subscription receives `email.failed` for it, not `email.bounced` | The same four `bounce*` fields, under the same names, are on `GET /api/emails/{id}` (and the list) and on the `BOUNCED` entry of that email's `events`. Branch on `bounceType`, `bounceSubType` and `bounceStatusCode`; `bounceDiagnosticCode` is free text from a remote mail server, so show it rather than parse it. Only `Permanent` bounces count toward your project's bounce rate and trigger automatic contact unsubscription. `Transient` bounces are tracked for visibility only. ```json { "subject": "Welcome to Sendly", "from": "hello@example.com", "fromName": "Sendly Team", "sesMessageId": "ses-message-id", "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "templateId": null, "campaignId": null, "sourceType": "TRANSACTIONAL", "complaintFeedbackType": "abuse", "complainedAt": "2025-01-15T10:35:00.000Z" } ``` | Field | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `complaintFeedbackType` | The label the recipient's mailbox provider attached to the complaint, as SES reports it: `abuse`, `auth-failure`, `fraud`, `not-spam`, `other` or `virus`. `null` when none was sent | | `complainedAt` | When the spam complaint was received | This event fires when an email is received at your verified domain. See [Receiving Emails](/guides/receiving-emails) for setup instructions. ```json { "sesMessageId": "ses-message-id", "from": "sender@example.com", "fromHeader": "Jane Smith ", "to": "support@yourdomain.com", "subject": "Re: Your question", "timestamp": "2025-01-15T10:30:00.000Z", "recipients": ["support@yourdomain.com"], "hasContent": true, "body": "This is the email body content...", "spamVerdict": "PASS", "virusVerdict": "PASS", "spfVerdict": "PASS", "dkimVerdict": "PASS", "dmarcVerdict": "PASS", "processingTimeMillis": 142 } ``` | Field | Description | | ---------------------- | --------------------------------------------------------------------- | | `sesMessageId` | The AWS SES message ID | | `from` | The sender's email address | | `fromHeader` | The full `From` header, including display name if present | | `to` | The recipient address at your verified domain | | `subject` | The email subject line | | `timestamp` | When SES received the email | | `recipients` | All recipient addresses in the envelope | | `hasContent` | Whether the email body content is available | | `body` | HTML body of the email (or plain text if no HTML available) | | `spamVerdict` | SES spam check result: `PASS`, `FAIL`, `GRAY`, or `PROCESSING_FAILED` | | `virusVerdict` | SES virus check result | | `spfVerdict` | SPF authentication result | | `dkimVerdict` | DKIM authentication result | | `dmarcVerdict` | DMARC authentication result | | `processingTimeMillis` | Time SES took to process the inbound email | #### Contact events [#contact-events-1] `contact.subscribed` and `contact.unsubscribed` carry no event data by default. The `event` field will be an empty object `{}`. The exception is when an unsubscription is triggered automatically by an email bounce or complaint — in that case `event` includes a `reason` field: ```json { "reason": "bounce" } ``` | Field | Value | | -------- | --------------------------------------------------- | | `reason` | `"bounce"` or `"complaint"` (when system-triggered) | #### Segment events [#segment-events-1] Both `segment..entry` and `segment..exit` include: ```json { "segmentId": "seg_abc123", "segmentName": "VIP Users" } ``` | Field | Description | | ------------- | ------------------------------- | | `segmentId` | The ID of the segment | | `segmentName` | The display name of the segment | #### Custom events [#custom-events] Custom events tracked via the API include whatever data you passed in the `data` field when calling `track`. #### No event data [#no-event-data] For events that carry no data, the `event` field will be an empty object `{}`. ## Correlating webhooks with send requests [#correlating-webhooks-with-send-requests] All email events include an `emailId` field that matches the Sendly email record ID returned when you send an email via `POST /api/emails`. This allows you to directly correlate webhook events with your API requests. **Example workflow:** 1. Send email via API: ```json POST /api/emails { "to": "user@example.com", "subject": "Welcome", "body": "Hello!" } Response: { "success": true, "data": { "emails": [ { "contact": {"id": "cnt_abc", "email": "user@example.com"}, "email": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf" } ] } } ``` 2. Store the `email` ID (`ac32f08e-c6b9-45d3-9824-a73dff1e3bbf`) in your database 3. When webhook events fire (e.g., `email.open`, `email.bounce`), match them using `event.emailId`: ```json { "event": { "emailId": "ac32f08e-c6b9-45d3-9824-a73dff1e3bbf", "sesMessageId": "ses-message-id", "openedAt": "2025-01-15T11:00:00.000Z" } } ``` This eliminates the need to match by contact email + timestamp or to listen for `email.sent` webhooks just to get the `sesMessageId`. ## Common use cases [#common-use-cases] ### Bounce and complaint monitoring [#bounce-and-complaint-monitoring] Create a workflow triggered by `email.bounce` or `email.complaint` to forward these events to your application. This allows you to keep your own database in sync with Sendly's contact statuses. You can use additional workflow steps before the webhook to add logic: - **Condition**: Only send the webhook for hard bounces by checking the `bounceType` field - **Delay**: Add a short delay to batch-process related events - **Update Contact**: Mark the contact with metadata before sending the webhook ### Syncing unsubscribes [#syncing-unsubscribes] Trigger a workflow on `contact.unsubscribed` to notify your application when a contact opts out. This is useful for keeping subscription status synchronized across multiple systems. ### Custom event forwarding [#custom-event-forwarding] If you track custom events in Sendly (e.g. `user.signup`, `order.completed`), you can forward those same events to other services via webhooks. This turns Sendly into an event router — track once, distribute to multiple endpoints. ## Send events to Slack [#send-events-to-slack] Webhook endpoints you add under **Settings → Webhooks** can point straight at a Slack channel. When the URL is a Slack incoming webhook, Sendly posts a readable Slack message instead of the JSON payload, which Slack would reject. 1. In Slack, create an app (or open an existing one), turn on **Incoming Webhooks**, and choose **Add New Webhook to Workspace**. Pick the channel and copy the URL. It looks like `https://hooks.slack.com/services/T000/B000/XXXX`. 2. In Sendly, open **Settings → Webhooks**, choose **New webhook**, paste the URL, and select the events you want in the channel. 3. Use **Send test** to post a sample message. It is marked `[Test]` so nobody mistakes it for a real event. Each message has a title for the event, the details that event carries (recipient, subject, sender, bounce type or failure reason, campaign and email IDs), and a footer with the project name, event type and time. Values from the email are shown as plain text, so a subject like `` never notifies your channel. Only URLs on `hooks.slack.com` under `/services/` over HTTPS are treated as Slack. Every other URL keeps receiving the JSON payload. Sendly still sends its signature headers to Slack, and Slack ignores them. Failed deliveries are retried on the usual schedule. ## Adding conditions and delays [#adding-conditions-and-delays] Since webhooks are part of the workflow system, you can combine them with other step types for more advanced setups: - Use a **Condition** step to only fire the webhook when certain criteria are met (e.g. only notify for contacts on a specific plan) - Use a **Wait for Event** step to wait for a follow-up event before sending the webhook (e.g. wait to see if a bounced contact re-subscribes) - Use a **Delay** step to add a time buffer before the webhook fires --- # MCP Server (/guides/mcp) Sendly runs a remote [Model Context Protocol](https://modelcontextprotocol.io) 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](/agent-setup) for the exact command per client, or paste the [agent-setup prompt](/agent-setup#pick-your-agent) into the agent itself and let it run the setup. ### Claude (web and desktop) [#claude-web-and-desktop] One click: [Add Sendly to Claude](https://claude.ai/directory/sendly) 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. The MCP endpoint accepts an OAuth access token **or** a Sendly secret key (`sk_…`). OAuth suits a person connecting a desktop client: you approve permissions on a consent screen and manage the connection in **Settings → Connected apps**. A secret key suits a headless or CI agent: the key's own permissions are what the agent may do, and you manage it in **Settings → API keys**. Sending-only keys (`pk_…`) and dashboard sessions are still refused — a `pk_` key can only send, and a session is a browser credential nobody aimed at an agent. ## 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](https://claude.ai/directory/sendly) 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](#claude-code), then `/mcp` to 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`: ```toml [mcp_servers.sendly] url = "https://app.sendly.now/api/mcp" ``` ### Cursor [#cursor] One click: [Add to Cursor](https://cursor.com/install-mcp?name=sendly&config=eyJ1cmwiOiJodHRwczovL2FwcC5zZW5kbHkubm93L2FwaS9tY3AifQ%3D%3D). Or in `.cursor/mcp.json`: ```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](https://insiders.vscode.dev/redirect/mcp/install?name=sendly&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.sendly.now%2Fapi%2Fmcp%22%7D). Or run *MCP: Add Server* → *HTTP* and paste the URL, which writes to `.vscode/mcp.json`: ```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): ```bash 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): ```json { "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 `@Sendly` in a chat. (Custom apps are currently limited to personal Google accounts in the US.) - **Gemini CLI:** `gemini extensions install https://github.com/DevinoSolutions/mcp-servers` then `/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](https://kiro.dev/launch/mcp/add?name=sendly&config=%7B%22url%22%3A%22https%3A%2F%2Fapp.sendly.now%2Fapi%2Fmcp%22%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%7D). Or in `.kiro/settings/mcp.json`: ```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](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6IlNlbmRseSIsImJhc2VVcmwiOiJodHRwczovL2FwcC5zZW5kbHkubm93L2FwaS9tY3AifQ%3D%3D), 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](https://github.com/DevinoSolutions/mcp-servers/tree/main/sendly) 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](#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: 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 `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. A key created before Sendly had per-capability permissions carries only the old coarse `FULL` / sending-only setting. Its scopes are **inferred** from it: a `FULL` key gets every tool those scopes name, the send tools included, except the two mailbox-conversation permissions, which only a key that names them conveys. Deleting and sending still ask for a confirmation on every 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_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. `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](#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_(...)` 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_(...)` 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 `:
    `, for example `CONFIRMATION_REQUIRED: …` or `INVALID_ARGUMENTS: …`, using the same codes as [Troubleshooting](#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](#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` | A tool that cannot be undone — `send_campaign`, `send_email`, the mailbox sends, and every `delete_…` — first answers `CONFIRMATION_REQUIRED` with a single-use `confirmToken` in `next.args`. The agent tells you exactly what will happen, and calls again with those arguments only if you agree. Nothing is sent or deleted by the first call — the check runs before Sendly's own API is touched. 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". Setting `enabled` to false — through `update_workflow` or `edit_workflow` — stops the workflow being *triggered* again and leaves every contact already part-way through it walking the steps. The next delay still expires and the next email still sends. **`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. ```json title="GET /api/v1/workflows/{id}/graph" { "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 [#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_conversations` and `get_mailbox_conversation` require `mailbox-conversations:read`; `reply_to_mailbox_conversation` requires `mailbox-conversations:reply`. Existing grants do not include these permissions. `get_mailbox` returns 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_signature` saves a plain-text signature (at most 1000 characters and 12 lines; no HTML) and `get_mailbox` shows it. A mailbox has one signature, so there is nothing to choose between. `send_mailbox_email` and `reply_to_mailbox_conversation` take `includeSignature`: 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; pass `false` to 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 in `signatureIncluded`. 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's `includeOnNewMessages` and `includeOnReplies` switches are what its owner chose for the dashboard composer; they do not stop an agent's send, so an agent that should honour them reads `get_mailbox` and passes `false`. Calling the REST routes directly is unchanged: `includeSignature` there still defaults to `false`. - **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 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. `create_mailbox` and `delete_mailbox` require a signed-in connection whose user is an **admin** of the project. An API key carries no user at all, so those two tools are never offered to a key connection — they are absent from its tool list rather than failing when it tries. `list_mailboxes` and `get_mailbox` work normally with a key. 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](#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` changes 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. This is the one capability that escapes its own revocation. A key minted here is a separate credential: it consults no consent row, it keeps working after you disconnect the app that asked for it, and you revoke it from **Settings → API keys** rather than from **Settings → Connected apps**. That is the whole reason `api-keys:write` carries a warning, and revoking a key asks the agent to confirm. ### 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. Relay it to you and say it opens once. A well-behaved client may also offer to open the window for you — that is an optional extra, not the mechanism. **The tool is complete either way**, because the URL is in the result the model can read out. If your client never offers to open anything, nothing is broken and nothing has been skipped. ## 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](#troubleshooting) lists every code. The agent brief at [docs.sendly.now/agent-setup/prompt.md](https://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 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 [#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](mailto:support@sendly.now) | Your MCP client's own approval prompt is what asks you before an irreversible tool runs, and it asks because of its own policy — most clients confirm every tool call, or every call you have not already approved for the session. Sendly does not trigger it. 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](#campaigns): 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. The [API reference](/api-reference/overview) is generated from Sendly's OpenAPI contract, so every route named on this page has its own page there, with the full request and response schemas. The `sendly-js` and `sendly-python` SDKs are generated from that same contract on their own release cadence, so a route added since their last release reaches them at the next one. Until then it is reachable the way everything here is: over HTTP with your key, or through the MCP tool that wraps it. Per-client setup commands, and a prompt an agent can fetch and run itself Server-to-server credentials — for your own code, and for connecting a headless agent The REST surface every MCP tool call goes through ## 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. ```json { "mailboxId": "", "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. --- # Integrations (/integrations) There is no first-party Sendly app in the Zapier, Make or n8n marketplaces yet. What there is instead is the thing those apps are made of: a documented REST API with a stable machine-readable spec, and a webhook subscription API that lets a platform register and tear down its own listeners. This page is that surface, named exactly. Every row is an operation in [the OpenAPI document](https://docs.sendly.now/openapi.json), and the `operationId` column is the name a generated client will give it. ## Authenticating [#authenticating] An API key, sent as `Authorization: Bearer sk_…`. Create one in **Settings → API keys**. Build against a **test-mode key** (`sk_test_…`) while you are wiring things up. A test key is the same credential with one thing taken away: it may only send from the project's sandbox address, whose recipients are limited to the project's own verified members, so a loop in a half-finished integration cannot put mail in a customer's inbox. See [API keys](/guides/api-keys) for the prefix scheme and what the mode does and does not change. ## Triggers [#triggers] Triggers are outbound webhooks. Sendly's webhook API is shaped for the REST-hook pattern that Zapier and n8n both use: the platform calls `createWebhook` when a user turns a trigger on, and `deleteWebhook` when they turn it off. | Operation | Method and path | What it is for | | --------- | --------------- | -------------- | | `createWebhook` | `POST /api/webhooks` | Subscribe. Takes a URL and the event types to receive. | | `deleteWebhook` | `DELETE /api/webhooks/{id}` | Unsubscribe. | | `listWebhooks` | `GET /api/webhooks` | The project's existing subscriptions. | | `getWebhook` | `GET /api/webhooks/{id}` | One subscription. | | `updateWebhook` | `PATCH /api/webhooks/{id}` | Change the URL, the event list, or the status. | | `rotateWebhookSecret` | `POST /api/webhooks/{id}/rotate-secret` | New signing secret. | | `listWebhookCalls` | `GET /api/webhooks/{id}/calls` | Delivery history — the first place to look when a trigger stops firing. | Which event types a subscription may name is a fixed list, and it is **not** the same list a workflow triggers on. That distinction has its own page: [Event vocabularies](/integrations/event-vocabulary). Read it before you hardcode a name. ## Actions [#actions] ### Sending [#sending] | Operation | Method and path | Notes | | --------- | --------------- | ----- | | `v1SendEmail` | `POST /api/v1/emails` | The current send endpoint. | | `sendEmail` | `POST /api/emails` | The older path, still supported. | | `sendEmailBatch` | `POST /api/emails/batch` | Many messages in one request. | | `listEmails` | `GET /api/emails` | For a "find a message" search step. | | `getEmail` | `GET /api/emails/{id}` | Status of one message. | ### Audience [#audience] | Operation | Method and path | Notes | | --------- | --------------- | ----- | | `upsertContact` | `POST /api/contacts/upsert` | The right action for a sync: create or update by email, idempotent. | | `createContact` | `POST /api/contacts` | Fails on a duplicate. | | `listContacts` | `GET /api/contacts` | Cursor-paginated. | | `getContact` | `GET /api/contacts/{id}` | | | `updateContact` | `PATCH /api/contacts/{id}` | | | `deleteContact` | `DELETE /api/contacts/{id}` | | | `bulkCreateContacts` | `POST /api/contacts/bulk` | For an import step rather than a per-record one. | | `subscribeToList` | `POST /api/lists/{id}/subscribe` | | | `unsubscribeFromList` | `POST /api/lists/{id}/unsubscribe` | | ### Suppression [#suppression] Any integration that sends on a customer's behalf has to respect this list, and any integration that syncs an audience outward should read it. | Operation | Method and path | | --------- | --------------- | | `listSuppressions` | `GET /api/suppression` | | `addSuppression` | `POST /api/suppression` | | `checkSuppression` | `GET /api/suppression/{email}` | | `removeSuppression` | `DELETE /api/suppression/{email}` | ### Campaigns and events [#campaigns-and-events] | Operation | Method and path | Notes | | --------- | --------------- | ----- | | `v1CreateCampaign` | `POST /api/v1/campaigns` | | | `v1SendCampaign` | `POST /api/v1/campaigns/{id}/send` | | | `v1GetCampaignStats` | `GET /api/v1/campaigns/{id}/stats` | | | `v1TrackEvent` | `POST /api/v1/events` | Record a custom event, which can fire a workflow. | | `v1ListEvents` | `GET /api/v1/events` | | ## Building an n8n community node [#building-an-n8n-community-node] The spec at `https://docs.sendly.now/openapi.json` is the released contract, and it is what a node generator should be pointed at. Three properties it holds, which are what a generated node depends on: - every operation has an `operationId`; - they are unique across the whole document; - they are lower camel case with no punctuation, so they survive being pasted into generated source. Those three are enforced by a test, not by convention, and so is the fact that the operationIds on this page keep pointing at the same method and path. An operationId is not visible in a `curl` command, so renaming one breaks every generated client without failing anything loudly — which is exactly why it is pinned. ## Zapier and Make [#zapier-and-make] Both are built the same way: a REST-hook trigger backed by `createWebhook` / `deleteWebhook`, and actions backed by the tables above. The signature on the delivered payload is what the trigger should verify — see [Webhooks](/guides/webhooks) for the header and the scheme. ## Segment [#segment] There is no published Segment destination. A destination built against this API would map: - `identify` → `upsertContact`; - `track` → `v1TrackEvent`; - a suppression or unsubscribe signal → `addSuppression` or `unsubscribeFromList`. ## What is not here yet [#what-is-not-here-yet] Said plainly, so nobody builds on an assumption: - **No first-party automation apps.** Nothing is published in the Zapier, Make, n8n or Segment catalogues. Everything above is what someone else can build with today. The one app Sendly ships itself is for [Slack](/integrations/slack), and it posts alerts rather than running automations. - **No campaign-level webhook events.** A subscription can hear about individual messages, not about a campaign starting or finishing. A platform that wants "when a campaign completes" has to poll `v1GetCampaignStats`. - **Two paths, one API.** Newer resources are versioned under `/api/v1/…`; contacts, templates, domains, webhooks and suppression are documented at their unversioned `/api/…` paths. Both are in the same spec and both are supported. Generate from the spec rather than assuming a prefix. --- # Slack (/integrations/slack) The **Sendly Slack app** posts a project's delivery alerts into one Slack channel you choose: bounce and complaint spikes, failed sends, finished campaigns, domain verification results, manual suppressions and usage-limit warnings. In that channel, the `/sendly` command answers with the project's delivery figures and the state of its sending domains. A post carries counts and settings only, never a recipient's address, a subject line or a message body. ## Connecting a project [#connecting-a-project] 1. In Sendly, open **Settings → Slack** for the project. You need to be an admin of the project. 2. Select **Add to Slack**. Slack shows what the app asks for and lets you pick the channel it will post to. 3. Approve. You come back to **Settings → Slack**, which shows the workspace and channel. Slack's approval screen names the app, the workspace and the channel the app will post to: ![Slack's approval screen for the Sendly app, with a workspace picker, a channel picker and the Cancel and Allow buttons](/assets/slack/slack-consent.webp) Once connected, **Settings → Slack** shows the workspace, the channel and the notices that post: ![Sendly's Settings, Slack page, showing the project connected to a Slack workspace, the channel it posts to and the list of notices to post](/assets/slack/slack-settings-connected.webp) Each project posts to one channel. Installing again from the same page replaces the connection, which is how you move the alerts to another channel. Several projects can post into the same workspace, each to its own channel or to a shared one. If you start the install from a link outside Sendly, such as the app's page in Slack, Sendly does not know which project you mean. After you approve, it asks you to choose one of the projects you administer. That step only works in the browser that started the install, within 30 minutes of starting it. ## Which notices post [#which-notices-post] All of them are on when you connect. Turn any of them off under **Settings → Slack → Notices to post**. | Notice | Posts when | | ------ | ---------- | | Bounce spikes | 5 or more bounces within 15 minutes. | | Complaint spikes | 2 or more spam complaints within 15 minutes. | | Failed deliveries | 5 or more failed sends within 15 minutes. | | Campaign finished sending | A campaign has been sent to all its recipients. | | Domain verified | A sending domain passed verification. | | Domain verification failed | A sending domain could not be verified. | | Manual suppressions | An address was suppressed by hand or through the API. | | Usage limit warning | Sending is approaching the monthly limit. | | Usage limit reached | The monthly sending limit has been reached. | The three spike notices are digests: one post says how many events arrived in the window, and the same kind does not post again for an hour. A manual suppression posts once and then keeps the channel quiet for 15 minutes, so suppressing a whole list through the API does not post once per address. The post says how long the quiet period lasts. ## The /sendly command [#the-sendly-command] | Command | Answers with | | ------- | ------------ | | `/sendly stats` | How many emails were sent recently, the delivered, bounce and complaint rates, and this month's usage against the limit. | | `/sendly domains` | Each sending domain and whether it is verified. | | `/sendly help` | The list of commands. | The answer is visible only to the person who typed the command. The command answers for the project connected to the channel it is typed in. Typed in any other channel, it says the channel is not connected and does not name the right one. Typed in a channel that two projects post to, it says so instead of picking one. `/sendly stats` reads figures Sendly recounts every 15 minutes, not a live count, so a recent send may not be in it yet. The answer says when the figures were counted. In the connected channel, `/sendly stats` and `/sendly domains` answer to you alone, and a notice such as a manual suppression posts for everyone in the channel: ![A Slack channel showing the answers to /sendly stats and /sendly domains, followed by a Sendly post titled Address suppressed](/assets/slack/slack-channel-alerts.webp) ## What the app can do in Slack [#what-the-app-can-do-in-slack] Sendly asks Slack for two permissions and nothing else: | Permission | Why | | ---------- | --- | | `incoming-webhook` | To post to the one channel picked during install. It cannot read that channel or post anywhere else. | | `commands` | To add the `/sendly` command. | The app cannot read messages, list channels or members, or see who is in the workspace. ## What Sendly stores [#what-sendly-stores] For each connected project, Sendly keeps: - the workspace's name and ID, and the channel's name and ID; - the channel's posting address and the app's token for the workspace, both encrypted; - which notices are on; - which Sendly user connected it. It does not store the Slack user ID of whoever approved the install, and it never shows the posting address or the token in Sendly, the API or a log. ## Disconnecting [#disconnecting] - **From Sendly:** **Settings → Slack → Disconnect**. Sendly deletes the connection at once. When no other Sendly project uses the same workspace, it also revokes the app's token at Slack. - **From Slack:** remove the Sendly app from the workspace. Slack tells Sendly, and Sendly deletes every project's connection to that workspace. If Slack reports that the channel no longer exists (it was deleted, or the app was removed from it), Sendly deletes the connection the next time it tries to post. After five failed posts in a row it stops trying for five minutes, so a Slack outage does not delay anything else. ## Troubleshooting [#troubleshooting] - **"This channel is not connected to a Sendly project."** The command was typed outside the channel the app posts to. Run it in that channel; **Settings → Slack** names it. - **"That install link expired or was opened in another browser."** The install has to finish in the browser that started it, and Slack's approval screen has to be answered within ten minutes. Start again from **Add to Slack**. - **"The install was started from a different Sendly account."** You signed in as someone else while Slack was open. Sign in as the account that selected **Add to Slack**, or start again. - **"Slack is not set up on this deployment."** The Sendly you are using has no Slack app registered. On sendly.now it is always set up; on a self-hosted Sendly, see below. ## Self-hosting [#self-hosting] A Sendly deployment without a Slack app still starts, and every Slack address answers `503` with the code `SLACK_NOT_CONFIGURED`. To turn it on: 1. At [api.slack.com/apps](https://api.slack.com/apps), choose **Create New App → From a manifest** and paste `apps/web/integrations/slack/manifest.json` from the Sendly repository, with `app.sendly.now` replaced by your dashboard's host in all three URLs. 2. From the app's **Basic Information** page, copy the client ID, client secret and signing secret into `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET` and `SLACK_SIGNING_SECRET`, and restart the web app. 3. Optionally, under **Manage Distribution**, set the direct install URL to `https:///integrations/slack/install`. All three variables are needed. With any of them missing, Slack stays off. --- # Event vocabularies (/integrations/event-vocabulary) Sendly names events in two places, and the names are not the same in both. Nothing warns you about this: a name from the wrong list is either rejected as invalid or, worse, accepted as a custom event that will never fire. - **Webhook subscription events** are what `createWebhook` accepts in `eventTypes`. A fixed list of ten. Anything else is a 400. - **Workflow trigger events** are what the system records on the timeline and what a workflow's event trigger matches on. A longer list, plus your own custom names. Four names appear in both lists and mean the same thing in each: `email.sent`, `email.opened`, `email.clicked` and `contact.unsubscribed`. Every other name belongs to one list only, and three pairs are near-misses that differ by a letter or two. The past tense is the tell, and it is not reliable. A subscription wants `email.delivered`; a workflow triggers on `email.delivery`. A subscription wants `email.bounced`; a workflow triggers on `email.bounce`. ## Webhook subscription events [#webhook-subscription-events] The ten values `POST /api/webhooks` accepts. A subscription names one or more of them. | Event | When it fires | | ----- | ------------- | | `email.sent` | The message was handed to the sending infrastructure. | | `email.delivered` | The recipient's server accepted it. | | `email.opened` | The message was opened. | | `email.clicked` | A link in the message was clicked. | | `email.bounced` | The message hard-bounced. A soft bounce does not fire this. | | `email.complained` | The recipient marked it as spam. | | `email.failed` | The send failed before or at handoff — rejected, or unrenderable — or the mail server gave up on it afterwards: it expired in the queue, or was finally refused for a reason that says nothing against the address. | | `contact.created` | A contact was created, by any route including an import. | | `contact.unsubscribed` | A contact's status changed to unsubscribed. | | `contacts.bulk_created` | A bulk import finished creating contacts. | ## Workflow trigger events [#workflow-trigger-events] What the system records and what a workflow's event trigger matches. You do not subscribe to these; you build a workflow whose trigger names one. Recorded by Sendly itself: | Event | When it fires | | ----- | ------------- | | `email.sent` | The message was handed to the sending infrastructure. | | `email.opened` | An open was recorded — by Sendly's tracking pixel, or by the provider's own open tracking. | | `email.clicked` | A click was recorded — by Sendly's rewritten link, or by the provider's own click tracking. | | `email.received` | Inbound mail arrived on a verified domain. | | `contact.subscribed` | A contact's status changed to subscribed. | | `contact.unsubscribed` | A contact's status changed to unsubscribed. | | `mailbox.message.received` | A message arrived in a Sendly mailbox. | | `mailbox.message.sent` | A message was sent from a Sendly mailbox. | Recorded from the sending infrastructure's own reports: | Event | When it fires | | ----- | ------------- | | `email.delivery` | The recipient's server accepted the message. | | `email.bounce` | The message bounced, hard or soft. | | `email.complaint` | The recipient marked it as spam. | | `email.reject` | The message was refused before it was sent. | | `email.renderingfailure` | A template variable could not be rendered. | | `email.deliverydelay` | Delivery is being retried after a temporary failure. | Two independent things detect an open: Sendly's tracking pixel and the provider's own open tracking. They used to record it under two different names, so a workflow saw whichever half it had named. Both now record `email.opened`, and clicks likewise record `email.clicked` — which means one message can fire the trigger more than once, because both detectors can see the same open. A workflow on these names should be written to tolerate that. If you are counting opens, read the message's own `opens` field rather than counting events. A webhook subscribes to `email.delivered`; a workflow triggers on `email.delivery`. Same for `email.bounced` against `email.bounce`, and `email.complained` against `email.complaint`. The names come from different places and neither list is going to silently change under a running integration, so check the list you are actually using rather than assuming the other one's spelling. ## Names you make up [#names-you-make-up] Two more kinds of trigger name exist, and neither is on a fixed list: - **Segment membership.** A segment called "VIP Users" produces `segment.vip-users.entry` and `segment.vip-users.exit`. The slug is derived from the segment's name, so renaming the segment renames its events. - **Your own events.** `POST /api/v1/events` records any name you give it, and a workflow can trigger on it. This is how an integration turns something that happened in another system into something Sendly can act on. A workflow trigger on a name nothing ever records is not an error — it simply never fires. That is the failure mode this page exists to prevent. --- # Microsoft 365 Copilot (/integrations/microsoft-365-copilot) The Sendly agent for Microsoft 365 Copilot lets you work in your Sendly account from Copilot chat. It reads your delivery status, sending domains, contacts and campaign results, and it can add a contact or send an email, each after you confirm. The agent is submitted through Microsoft Partner Center and is not in the Microsoft store until Microsoft has reviewed and listed it. This page describes what it does and what it can reach, so you can decide before you connect it. ## What it can do [#what-it-can-do] | Function | What it does | Changes data | | --------------------- | ----------------------------------------------------------- | ------------- | | `listProjects` | Lists your Sendly projects | No | | `listRecentEmails` | Lists the emails a project sent most recently | No | | `getEmailStatus` | Gives the delivery status and history of one email | No | | `listDomains` | Lists sending domains and whether each is verified | No | | `listContacts` | Lists or searches contacts | No | | `listCampaigns` | Lists campaigns | No | | `getCampaignStats` | Gives delivered, opened, clicked and bounced for a campaign | No | | `createContact` | Adds one contact | Asks first | | `sendEmail` | Sends one email from a verified sending domain | Asks first | | `sendTestEmail` | Sends a sandbox test email to the project owner | Asks first | These are operations of the public [OpenAPI document](https://docs.sendly.now/openapi.json); the agent calls them as you, with the permissions you approve. ## Confirmation [#confirmation] Reading never changes anything. The three functions that add a contact or send mail stop and show you the details, such as the recipient and subject, and wait for you to approve. A sandbox test email can only reach the owner of the project, never a customer. ## Signing in and permissions [#signing-in-and-permissions] The first time you use the agent, Microsoft 365 Copilot sends you to the Sendly sign-in and consent screen. It uses the same OAuth flow as Sendly's other connected apps, and shows each permission with a sentence saying what it allows. | Permission | Allows | | ---------------- | ------------------------------------------------------------ | | `projects:read` | See your projects and their settings | | `emails:read` | See the emails you sent and their delivery status | | `emails:send` | Send emails from your verified domains | | `emails:test` | Send test emails to your own address from the Sendly sandbox | | `domains:read` | See your sending domains and their verification status | | `contacts:read` | See your contacts | | `contacts:write` | Add and update your contacts | | `campaigns:read` | See your campaigns and their performance | Leave `emails:send` and `contacts:write` unchecked and the agent can still answer every question; it only cannot send or add. Disconnect the agent at any time from your Sendly account, and its access ends. The agent works on one project at a time. It asks which one when you have several, and never combines data from two projects. ## What to ask [#what-to-ask] - Show my most recent emails and how they were delivered - Are my sending domains verified? - How did my latest campaign perform? - Add maria@example.com as a subscribed contact ## Data [#data] The agent sends your questions and Sendly's answers through Microsoft 365 Copilot. What Sendly keeps, and for how long, is in the [privacy policy](https://sendly.now/privacy). What Microsoft does with the conversation is covered by your Microsoft 365 agreement. ## For developers [#for-developers] The agent package (manifest, declarative agent, plugin and a trimmed OpenAPI file) lives in the Sendly repository under `apps/web/integrations/microsoft-365`. If you would rather connect an AI client directly, use the [MCP server](/guides/mcp). --- # Glossary (/glossary) Email carries a lot of vocabulary from the 1980s, and most of it is only explained in RFCs. These are the terms you will meet in Sendly's dashboard, in an API error, or in a conversation about why a message did not arrive — each defined in a paragraph, with a link to the part of the documentation that shows you what to do about it. Every entry says what the term means in general and, where the two differ, what Sendly specifically does with it. Where Sendly does not implement something, the entry says so rather than describing the general case as if it were ours. ## Sending domains [#sending-domains] The domain your mail claims to come from, and the thing you verify. A DNS record listing who is allowed to send for your domain. A cryptographic signature proving a message was not altered in transit. Your published policy for mail that fails SPF and DKIM. The envelope address bounces come back to, which is not the From address. The DNS record saying which server receives mail for a domain. ## Deliverability [#deliverability] Whether your mail reaches the inbox, as distinct from being accepted. The score mailbox providers keep on your domain and your sending IPs. A delivery failure, and why the hard and soft kinds are not the same problem. What happens when a recipient presses the spam button. The addresses Sendly refuses to mail, and why you cannot simply delete them. Building a sending reputation gradually rather than all at once. ## Consent [#consent] Confirming a subscription by email before you mail anyone. The header that puts an unsubscribe link in the mail client itself. ## Sending [#sending] A message sent to one person because of something they did. A message sent to an audience, which needs consent and an unsubscribe. One broadcast to a list or a segment, at a time you choose. An automated sequence that reacts to data and behaviour. A rule-defined slice of your contacts that keeps itself current. The placeholder a contact's own data is substituted into. What makes retrying a send safe rather than a duplicate. ## Data coming back out [#data-coming-back-out] Sendly calling your server when something happens. How opens are measured, and why the number is a floor rather than a count. The protocol an AI agent uses to work in your Sendly account. --- # Sending domain (/glossary/sending-domain) A **sending domain** is the domain in the address your mail comes from — `yourcompany.com` in `hello@yourcompany.com`. Before any platform sends on your behalf, it has to establish that you actually control that domain, because the alternative is a platform that will send mail claiming to be from anyone. You prove it by publishing DNS records: an [SPF](/glossary/spf) record naming the services allowed to send for you, a [DKIM](/glossary/dkim) key so signatures can be verified, and usually a [DMARC](/glossary/dmarc) policy saying what a receiving server should do with mail that fails both. A sending domain can be your root domain or a subdomain such as `mail.yourcompany.com`. Each one is verified on its own and builds its own [sender reputation](/glossary/sender-reputation). It is the domain in the **From** address, which is different from the envelope domain that carries bounces (see [Return-Path](/glossary/return-path)). ## In Sendly [#in-sendly] A project must have at least one verified sending domain before it can send anything, including through a compat endpoint. Verification is a DNS change, so it is the step in a migration whose timing you control least — start it first. [Guided DNS setup](/guides/guided-dns-setup) can publish the records for you and then keep checking them afterwards, which matters more than it sounds: a registrar migration or an unrelated edit that drops a DKIM record is otherwise discovered through a delivery failure weeks later. See [Verifying domains](/guides/verifying-domains) for the manual path and the record values. --- # SPF (/glossary/spf) **SPF**, Sender Policy Framework, is a TXT record on your domain that lists which mail servers may send for it. A receiving server looks up the record, compares it against the address in the message envelope, and gets back a pass, a fail, or a softer verdict. A record looks like this: ``` v=spf1 include:amazonses.com ~all ``` `include:` delegates to another sender's own record — here, the infrastructure Sendly sends through. `~all` means anything not listed is suspicious; `-all` means anything not listed is forged. ## Two things people get wrong [#two-things-people-get-wrong] **SPF checks the envelope sender, not the From address a human sees.** Those are different addresses — see [Return-Path](/glossary/return-path). This is exactly why SPF alone was never enough, and why [DMARC](/glossary/dmarc) exists. **A domain may have only one SPF record.** Two TXT records both beginning `v=spf1` is a permanent error rather than a merge, and it fails every check at once. Adding a sender means adding an `include:` to the record you already have. There is also a limit of ten DNS lookups while evaluating a record. Each `include:` counts toward it, and exceeding it is a failure rather than a truncation. ## In Sendly [#in-sendly] The SPF value you need is shown when you add a domain, and [guided DNS setup](/guides/guided-dns-setup) can publish it and watch it. See [Verifying domains](/guides/verifying-domains). --- # DKIM (/glossary/dkim) **DKIM**, DomainKeys Identified Mail, signs each outgoing message with a private key and publishes the matching public key in your DNS. A receiving server fetches the key, checks the signature, and learns two things: that the message really was sent by something holding your key, and that the headers and body it signed were not altered on the way. Unlike [SPF](/glossary/spf), DKIM survives forwarding. A mailing list that relays your message leaves the signature intact as long as it does not rewrite what was signed, which is why DKIM is the stronger of the two signals and why [DMARC](/glossary/dmarc) can pass on DKIM alone. ## What a record looks like [#what-a-record-looks-like] A CNAME or TXT record at a selector-scoped name, for example `abc123._domainkey.yourcompany.com`. The selector lets one domain carry several keys at once, which is what makes rotating a key possible without an outage. ## In Sendly [#in-sendly] Keys are generated for you when you add a domain, and the records to publish are shown in the dashboard. A verified domain whose DKIM record later disappears stops passing — [guided DNS setup](/guides/guided-dns-setup) watches for exactly that. One migration gotcha worth knowing: if you are moving from a provider that also managed DKIM for this domain, delete their records rather than leaving them. A stale key is not harmful on its own, but it makes diagnosing the next problem considerably harder. See [Verifying domains](/guides/verifying-domains). --- # DMARC (/glossary/dmarc) **DMARC**, Domain-based Message Authentication, Reporting and Conformance, ties [SPF](/glossary/spf) and [DKIM](/glossary/dkim) to the From address a human actually sees, and publishes your instruction for what should happen when both fail. A record looks like this: ``` v=DMARC1; p=reject; rua=mailto:dmarc@yourcompany.com ``` `p=` is the policy: `none` (do nothing, just report), `quarantine` (treat as suspicious, usually the spam folder), or `reject` (refuse outright). `rua=` is where aggregate reports are sent, and those reports are how you find out which of your systems is sending mail you had forgotten about. ## Alignment is the part that surprises people [#alignment-is-the-part-that-surprises-people] DMARC passes when SPF or DKIM passes **and** the domain that passed matches the domain in the From header. That second condition is called alignment, and it is why mail can pass SPF, pass DKIM, and still fail DMARC: the passing signal belonged to a different domain. ## How to roll it out [#how-to-roll-it-out] Start at `p=none` and read the reports for a few weeks. Move to `p=quarantine`, then to `p=reject`, and only once the reports show nothing legitimate failing. Publishing `p=reject` on day one is how an organisation discovers that its invoicing system was sending mail nobody remembered. ## In Sendly [#in-sendly] The record to publish is shown alongside your SPF and DKIM values, and [guided DNS setup](/guides/guided-dns-setup) can publish it. Sendly does not choose your policy for you: the escalation above is a decision about your own mail flow, including systems Sendly cannot see. --- # Return-Path header (/glossary/return-path) The **Return-Path** is the email address a message's delivery failures are sent back to. It is also called the envelope sender, the bounce address, the SMTP `MAIL FROM` address or the `5321.MailFrom`. It is not the address a reader sees: that is the **From** header. Every message carries both, and they are allowed to be different domains. They are separate on purpose. A mailing list can relay your message to a thousand people and take the bounces itself, without rewriting the From address the reader sees. ## What is the difference between Return-Path, From and Reply-To? [#what-is-the-difference-between-return-path-from-and-reply-to] Three addresses can appear on one message, and each is used by something different. | Property | Return-Path | From | Reply-To | | --- | --- | --- | --- | | Also called | Envelope sender, bounce address, `MAIL FROM` | Header From, `5322.From` | Reply address | | Where it lives | The SMTP envelope; copied into a header on delivery | A message header you write | A message header you write (optional) | | Shown to the reader | No, only in the raw source | Yes, as the sender | Only when they reply | | Used for | Bounces and delivery failure notices; the identity [SPF](/glossary/spf) checks | Who the message claims to be from; the identity [DMARC](/glossary/dmarc) protects | Where a reply is addressed, instead of From | | Set by | The sending server | You | You | In short: the Return-Path decides where **bounces** go, From decides who the message **claims to be from**, and Reply-To decides where **replies** go. ## Where does the Return-Path come from? [#where-does-the-return-path-come-from] The Return-Path is not a header the sender writes. During the SMTP conversation the sending server announces the envelope sender with the `MAIL FROM` command, which is why it is also called the **SMTP Return-Path** or MAIL FROM address. The server that finally delivers the message records that address at the top of the message as a `Return-Path:` header (RFC 5321, section 4.4). Writing a `Return-Path` header into the message yourself does not change the envelope; the delivering server writes the one that counts. Messages that report a failure, such as a bounce notice, are sent with an empty envelope sender (`<>`), so that a failure about a failure can never loop. ## How do I see the Return-Path of a message? [#how-do-i-see-the-return-path-of-a-message] Open the raw source of a message you received. The two addresses sit side by side and can be completely different: ```text title="Headers of a delivered message (abridged)" Return-Path: <0100019a...-000000@sendly.yourdomain.com> From: Acme To: customer@example.com Subject: Your receipt ``` - **Gmail:** open the message, choose the three-dot menu, then **Show original**. The `Return-Path:` line is near the top of the raw message. - **Outlook:** open the message and view its internet headers (**View message source** or **View message details** in Outlook on the web, **File > Properties** in the desktop app), then look for `Return-Path:`. ## Why does SPF check the Return-Path and not the From address? [#why-does-spf-check-the-return-path-and-not-the-from-address] [SPF](/glossary/spf) was designed to protect the SMTP envelope. A receiving server asks: is the server that is handing me this message allowed to send for the `MAIL FROM` domain? It does not look at the From header at all (RFC 7208). So a message can pass SPF on a domain the recipient never sees, and a message that shows your domain in From can still pass SPF on the sender's own envelope domain. That gap is exactly what DMARC was built to close. ## How does the Return-Path affect DMARC alignment? [#how-does-the-return-path-affect-dmarc-alignment] [DMARC](/glossary/dmarc) passes a message when SPF or [DKIM](/glossary/dkim) passes **and aligns** with the From domain. For SPF, alignment means the Return-Path domain matches the From domain: - **Relaxed alignment** (the default): the Return-Path domain only has to share the same organizational domain, so `sendly.yourdomain.com` aligns with `hello@yourdomain.com`. - **Strict alignment**: the two domains must be identical. If your provider uses its own domain as the Return-Path, SPF can pass and still not align, and DMARC then depends entirely on DKIM. A Return-Path on your own domain is what makes SPF count towards DMARC. ## What is a custom MAIL FROM domain? [#what-is-a-custom-mail-from-domain] A custom MAIL FROM domain is a subdomain of your sending domain that you point at your provider, so the Return-Path is an address on your domain instead of the provider's. It takes two DNS records on that subdomain: an MX record, so bounces and complaints are routed back to the provider, and a TXT record carrying an SPF policy that authorizes the provider to send for it. The subdomain is separate from your From domain, so it does not change where your own mail is received. ## What happens to bounces sent to the Return-Path? [#what-happens-to-bounces-sent-to-the-return-path] [Bounces](/glossary/bounce) arrive at the Return-Path. If that address is not monitored by whatever sends your mail, nobody learns that an address is dead, and you keep mailing it, which is a direct hit to [sender reputation](/glossary/sender-reputation). A sender that reads its bounces can stop mailing the dead address and add it to a [suppression list](/glossary/suppression-list). ## In Sendly [#in-sendly] Sendly sends through Amazon SES and gives every sending identity a **custom MAIL FROM subdomain**: `sendly.yourdomain.com` for `yourdomain.com`. Once its MX and SPF records are published (see [Custom MAIL FROM](/guides/verifying-domains#custom-mail-from-1-mx--1-txt-record)), the Return-Path on your mail is an address on that subdomain, unique to each message, as in the example above. That gives you two things: - **SPF alignment.** The envelope domain is a subdomain of your From domain, which is what DMARC's relaxed SPF alignment requires. - **Bounce handling.** Bounce and [complaint](/glossary/complaint) reports come back through SES and are processed for you, and the affected addresses land on your [suppression list](/glossary/suppression-list) automatically. You never choose or monitor the address itself. If the MX record on the subdomain is missing, mail still sends, but SES falls back to its own `amazonses.com` envelope sender, and SPF no longer aligns with your domain. The domain's **MAIL FROM** status in Sendly tells you which case you are in. To publish the records, follow [Verifying sending domains](/guides/verifying-domains) or let [guided DNS setup](/guides/guided-dns-setup) do it. Related terms: [sending domain](/glossary/sending-domain) and [MX record](/glossary/mx-record). --- # MX record (/glossary/mx-record) An **MX record** (Mail Exchanger) is the DNS record naming the server that accepts mail for a domain. When something sends to `you@yourcompany.com`, it looks up the MX record for `yourcompany.com` and delivers there. A domain with no MX record cannot receive mail at all. Records carry a priority number, lower being preferred, so a domain can list a backup that is used only when the primary is unreachable. ## Sending and receiving are separate [#sending-and-receiving-are-separate] Adding an MX record does not affect your ability to send, and verifying a domain for sending does not let you receive. The two directions use different records and different infrastructure, which is why a domain can be perfectly configured for one and not the other. That separation matters most when you already have mail somewhere. Pointing the MX record for a domain at a new service moves ALL inbound mail for it, so an existing mailbox on that exact domain stops receiving. Use a subdomain when you want both. ## In Sendly [#in-sendly] Inbound mail is a [mailbox](/guides/receiving-emails) feature: you point an MX record at Sendly's inbound host, and messages arriving for that domain become mailboxes you can read over IMAP, over SMTP, or through the API. The inbound host is Sendly's own, and not the sending infrastructure's — read the [receiving email guide](/guides/receiving-emails) for the exact value rather than inferring one. --- # Deliverability (/glossary/deliverability) **Deliverability** is whether your mail arrives where a person will see it. It is not the same as delivery: a message can be accepted by the receiving server, reported as delivered, and filed straight into the spam folder. Delivery is a protocol outcome, and deliverability is an outcome for a human. Nobody can guarantee it, and any provider claiming to is describing delivery. What a provider can do is remove the causes you control. ## What actually moves the number [#what-actually-moves-the-number] Roughly in order of how much they matter: - **Consent.** Mailing people who asked to hear from you produces engagement; mailing people who did not produces [complaints](/glossary/complaint). Nothing else on this list outweighs it. Purchased and scraped lists are the single fastest route to a ruined domain. - **List hygiene.** Repeatedly mailing dead addresses signals that you are not paying attention. See [bounce](/glossary/bounce), [suppression list](/glossary/suppression-list) and the [list hygiene guide](/guides/list-hygiene). - **Authentication.** [SPF](/glossary/spf), [DKIM](/glossary/dkim) and [DMARC](/glossary/dmarc) that pass, aligned to the domain in your From address. - **Consistency.** A steady volume beats a flat month followed by a million-message Tuesday. See [IP warm-up](/glossary/ip-warm-up). - **Content.** It matters least of the five, and it is where most advice concentrates. ## In Sendly [#in-sendly] Sendly handles the parts that are mechanical: authentication records via [guided DNS setup](/guides/guided-dns-setup), bounce and complaint processing, automatic [suppression](/glossary/suppression-list), and per-project sending limits that keep a sudden spike from being treated as an incident. The parts that are editorial — who is on your list, why they are on it, and what you send them — are yours, and they are the ones that decide the outcome. --- # Sender reputation (/glossary/sender-reputation) **Sender reputation** is the score a mailbox provider keeps on you. It has no public number, no API, and no appeal, and it decides whether your mail reaches the inbox, the spam folder, or nothing at all. It attaches to two things at once: the sending IP address, and your domain. Domain reputation is the one you carry with you. Changing providers gives you new IPs and does nothing at all for a domain you have spent a year teaching Gmail to distrust. ## What raises it and what wrecks it [#what-raises-it-and-what-wrecks-it] Providers do not publish their weightings, but the direction of each signal is not in doubt. - **[Complaints](/glossary/complaint) are the worst single signal.** A rate above roughly 0.1% — one in a thousand — is treated as a problem by most providers, and the threshold where filtering begins is lower than the threshold where anyone tells you. - **Hard [bounces](/glossary/bounce) at volume** say you are mailing a list you have not maintained. - **Spam-trap hits** are catastrophic, and they are the reason a purchased list is never worth it: a recycled trap is an address that was real, was abandoned, and is now watched. - **Engagement helps.** Opens, clicks and replies are positive signals; a large audience that never engages is a negative one even with no complaints at all. - **Volume consistency helps.** See [IP warm-up](/glossary/ip-warm-up). ## In Sendly [#in-sendly] Sending is on shared, actively monitored infrastructure with per-project limits, which means one sender's mistake is contained rather than borne by everyone. It also means the protective limits are real: a sudden order-of-magnitude jump in volume from a new project is exactly the shape those limits exist to catch. If you are about to migrate real volume, say so first. Sendly does not offer a self-serve dedicated IP with a warm-up schedule you control today. --- # Bounce (/glossary/bounce) A **bounce** is a delivery failure reported by the receiving server. There are two kinds, and treating them alike is one of the more expensive mistakes in email. ## Hard bounce [#hard-bounce] Permanent. The address does not exist, the domain does not exist, or the server has refused it outright. There is no retry that helps, and sending to it again is a signal to the mailbox provider that you do not maintain your list. A hard-bounced address must never be mailed again. In Sendly it goes onto your [suppression list](/glossary/suppression-list) automatically, so this is enforced rather than left to your discipline. ## Soft bounce [#soft-bounce] Temporary. A full mailbox, a server that is down, a message over a size limit, or throttling because you sent too fast. The right response is to retry later, and to stop retrying after a few failures — an address that soft-bounces for weeks is a hard bounce that has not admitted it yet. ## Why the ratio matters [#why-the-ratio-matters] [Sender reputation](/glossary/sender-reputation) is affected by the rate as much as the count. A high hard-bounce rate is read as a list that was bought, scraped, or left untouched for years, and providers respond by filtering the rest of your mail. ## In Sendly [#in-sendly] Bounce notifications arrive at the [Return-Path](/glossary/return-path), which Sendly monitors. Hard bounces are suppressed automatically. Bounce events also reach your [webhooks](/glossary/webhook) and appear in the delivery record for the message, so your own systems can react — marking the contact, pausing a workflow, or asking the customer for a new address. See [List hygiene](/guides/list-hygiene). --- # Complaint (/glossary/complaint) A **complaint** is what a recipient generates by pressing "report spam" or "junk". The mailbox provider reports it back to the sender through a feedback loop, and it is the single most damaging signal in email. The damage is not to that one message. It is to your [sender reputation](/glossary/sender-reputation), and therefore to every message you send afterwards, to everyone. ## The number to know [#the-number-to-know] A complaint rate above roughly **0.1%** — one in a thousand delivered messages — is treated as a problem by most major providers. That is a much smaller number than it sounds: on a 50,000-message campaign it is fifty people. Filtering usually begins well before anyone tells you it has. By the time deliverability is visibly bad, the reputation damage has already been done and takes weeks of good behaviour to undo. ## What causes them [#what-causes-them] Almost always one of three things, and almost never the content itself: - The recipient does not remember subscribing. See [double opt-in](/glossary/double-opt-in). - The unsubscribe link is hard to find, so the spam button is easier. See [List-Unsubscribe](/glossary/list-unsubscribe). - The mail is not what they expected — a different frequency, or a different subject, from what they signed up for. ## In Sendly [#in-sendly] Complaint notifications are processed automatically and the complaining address goes onto your [suppression list](/glossary/suppression-list) immediately. Complaint events also reach your [webhooks](/glossary/webhook). Sending mail to an address that has complained is not something you can opt out of being stopped from doing, and that is deliberate. --- # Suppression list (/glossary/suppression-list) Your **suppression list** is the set of addresses Sendly will not send to. An address on it is skipped before a message is composed, whatever asked for the send — an API call, a campaign, a workflow, or a compat endpoint. Entries arrive from three places: an unsubscribe, a [complaint](/glossary/complaint), and a hard [bounce](/glossary/bounce). All three are automatic, and that is the point. A suppression list that depends on someone remembering to update it is a suppression list that fails on the day it matters. ## Why you cannot casually clear it [#why-you-cannot-casually-clear-it] Removing an address means Sendly will mail someone who previously bounced permanently, asked to stop, or reported you as spam. Each of those is a direct hit to [sender reputation](/glossary/sender-reputation), and the last one may also be a legal problem depending on where the recipient lives. So removal is treated as a consequential act rather than a convenience: - It is a distinct API permission, `suppression:write`, separate from reading the list. - For an AI agent it is one of the eight permissions that arrive **unchecked** on the consent screen, with the consequence spelled out. See [the MCP guide](/guides/mcp). ## Migrating in [#migrating-in] Import your previous provider's unsubscribes, complaints and hard bounces **before** your first real send from Sendly. Sendly cannot know about a suppression that lives in another system, and the first campaign after a migration is the classic moment for mailing several thousand people who already asked you to stop. See [List hygiene](/guides/list-hygiene). --- # IP warm-up (/glossary/ip-warm-up) **IP warm-up** is the practice of increasing volume from a new sending IP gradually — starting with a few hundred messages a day to your most engaged recipients, and roughly doubling over a period of weeks — so that mailbox providers build a positive record before they see real volume. The reason it exists is that a brand-new IP has no reputation, and no reputation is treated as suspicious rather than neutral. A new IP that sends a million messages on its first day is behaving exactly like a compromised one. ## When it applies to you [#when-it-applies-to-you] Only when you have a **dedicated** IP. On shared infrastructure, the reputation of the IPs already exists and is maintained by the provider across all of its senders, so there is no IP to warm. What still applies on shared infrastructure is **domain** reputation, which is yours and travels with you. A domain that has never sent has the same problem an IP does, and the same answer: start with the people most likely to engage, and increase over weeks. ## In Sendly [#in-sendly] Sendly sends over shared, actively monitored infrastructure, with per-project sending limits on top. There is no self-serve dedicated IP with a warm-up schedule you control today; if that is a requirement, it is a conversation to have before you migrate rather than after. The per-project limits mean a first campaign of unusual size may be paced rather than released at once. That is protective, not a fault, and it is another reason to tell us before you move volume across. --- # Double opt-in (/glossary/double-opt-in) **Double opt-in** means a person who submits your signup form is not subscribed yet. They are sent one message with a confirmation link, and only a click on that link subscribes them. **Single opt-in** subscribes them on submission. Double opt-in costs you signups. Somewhere between ten and thirty per cent of people never click, and that is the real objection to it. ## Why it is usually still right [#why-it-is-usually-still-right] - It proves the address exists and belongs to the person who typed it, which removes typos, throwaway addresses and other people's addresses in one step. - It is the strongest available answer to "I never signed up for this", which is the most common reason for a [complaint](/glossary/complaint) — and complaints cost far more than the signups you lost. - It keeps spam traps off your list, which purchased and scraped lists cannot do at all. - In several jurisdictions it is the easiest way to evidence consent if anyone asks. The signups it costs were mostly never going to engage. The ones it keeps are the ones mailbox providers score you on. ## In Sendly [#in-sendly] Sendly does not force a subscription flow on you: subscription happens through the API or an import, so the confirmation step is yours to build. The pieces are all here — a transactional send for the confirmation message, a contact custom field or list membership to record the state, and a [workflow](/glossary/workflow) if you want to chase people who did not confirm. Whatever you choose, import your previous provider's [suppression list](/glossary/suppression-list) before your first send. --- # List-Unsubscribe (/glossary/list-unsubscribe) **List-Unsubscribe** is a header on a message that tells the mail client how to unsubscribe the reader. Gmail, Apple Mail and Outlook all read it and render their own unsubscribe control at the top of the message, next to the sender's name. Two forms exist, and modern practice is to send both: - A **URL**, which the client can call directly. The `List-Unsubscribe-Post` header signals that a one-click POST is supported, so the reader is never taken to a landing page. - A **mailto:** address, for clients that prefer it. ## Why you want it [#why-you-want-it] It is the cheapest complaint reduction available. When the easiest visible control is "unsubscribe", people use it. When the easiest visible control is "report spam", people use that instead — and a [complaint](/glossary/complaint) costs your [sender reputation](/glossary/sender-reputation) enormously more than an unsubscribe does. Bulk senders to the major providers are also now required to support one-click unsubscribe, so this is table stakes rather than an optimisation. ## The rule that goes with it [#the-rule-that-goes-with-it] An unsubscribe must be honoured promptly and without conditions. No login, no confirmation step, no survey. That is both the law in most places and the behaviour that keeps people from reaching for the spam button next time. ## In Sendly [#in-sendly] Marketing sends carry both headers. The URL in them is a signed, single-recipient link rather than a guessable contact id, which RFC 8058 requires for a good reason: the header is fetched unattended by scanners and previewers that will POST whatever they find, so a guessable one unsubscribes strangers. A one-click unsubscribe is applied when the request arrives, not queued behind a page or a confirmation. It stops marketing to that contact and switches off every topic they were subscribed to, so a later topic subscription cannot quietly resurrect the mail they just refused. A send through the API carries no unsubscribe of Sendly's, because Sendly cannot know what the reader would be opting out of. If you run the opt-out yourself (notification mail is the usual case), name your own endpoint in the send's `listUnsubscribe` field: an https URL, ideally carrying a token for the recipient. Sendly then adds both headers with that URL. The mail client POSTs `List-Unsubscribe=One-Click` to it with no cookies and no page in between, so the endpoint has to unsubscribe the reader on that request alone. Campaigns and workflows ignore the field and keep Sendly's own link. Two things Sendly's own one-click unsubscribe deliberately does not do. It does not stop [transactional](/glossary/transactional-email) mail, because a password reset is not something a marketing preference cancels. And it does not add the address to your [suppression list](/glossary/suppression-list) — that is a separate, project-wide block that you control and that applies to every send, transactional included. --- # Transactional email (/glossary/transactional-email) A **transactional email** is sent to one person as a direct result of something that person did or something that happened to their account: a receipt, a password reset, an order confirmation, a shipping notice, a security alert. The defining property is not the content. It is that the recipient is expecting it, because they caused it. ## Why the distinction matters [#why-the-distinction-matters] - **Consent works differently.** A transactional message does not need marketing consent, because it is part of a transaction the person entered into. That exemption is narrow: attach a promotion to a receipt and the message is marketing with a receipt on it. - **An unsubscribe link is not required** and is usually wrong. Nobody should be able to opt out of their own password reset. - **Timing matters more.** Nobody minds a newsletter arriving an hour late. A password reset an hour late is a support ticket. ## In Sendly [#in-sendly] Transactional sends go through the REST API and are the path the [compat endpoints](/migrate) translate. They draw on the same allowance as everything else: Sendly meters emails, not products, so transactional, campaign, workflow and inbound mail all count against one number. They are still subject to your [suppression list](/glossary/suppression-list). A hard [bounce](/glossary/bounce) means the address does not exist, and a receipt to a non-existent address helps nobody. See [Transactional emails](/concepts/transactional-emails) and the [send API](/api-reference/emails/v1SendEmail), and use an [idempotency key](/glossary/idempotency-key) so a retry cannot duplicate one. --- # Marketing email (/glossary/marketing-email) A **marketing email** is sent to an audience because you decided to send it — a newsletter, an announcement, an offer, a re-engagement message. Nobody triggered it by doing anything, which is what separates it from a [transactional email](/glossary/transactional-email). That difference brings three obligations, everywhere in the world with an email law worth the name: - **Consent.** The recipient must have agreed to hear from you. Purchased, rented and scraped lists do not clear this bar and are also the fastest route to a ruined [sender reputation](/glossary/sender-reputation). - **A working unsubscribe**, honoured promptly and without conditions. See [List-Unsubscribe](/glossary/list-unsubscribe). - **An identifiable sender**, including a real postal address in most regimes. The specific statutes differ — CAN-SPAM in the United States, CASL in Canada, the GDPR and ePrivacy rules in the EU and UK — but no regime lets you skip any of the three. ## The grey area [#the-grey-area] The exemption for transactional mail is narrower than most people assume. A receipt with a promotion on it is marketing. A "your trial is ending" notice is usually transactional; the same notice with three upsells is not. If the message would still be sent when the commercial part was removed, it is transactional. ## In Sendly [#in-sendly] Marketing goes out as a [campaign](/glossary/campaign) or through a [workflow](/glossary/workflow), usually to a [segment](/glossary/segment) or a list. [Unsubscribe headers](/glossary/list-unsubscribe) are attached, and an unsubscribe stops every marketing send to that address, every topic it was subscribed to included. It leaves [transactional](/glossary/transactional-email) mail alone. --- # Campaign (/glossary/campaign) A **campaign** is a single [marketing email](/glossary/marketing-email) sent to an audience: one piece of content, one recipient set, one send. A newsletter issue, a product announcement, a seasonal offer. It is a discrete event, which is what distinguishes it from a [workflow](/glossary/workflow) — a workflow keeps reacting to individual people over time, where a campaign happens once and is finished. ## What a campaign is made of [#what-a-campaign-is-made-of] - **An audience**, usually a [segment](/glossary/segment) rather than your whole contact list. - **Content**, either written inline or from a reusable template with [variables](/glossary/template-variable). - **A schedule**, now or at a chosen time. ## In Sendly [#in-sendly] Campaigns are a first-class API object as well as a dashboard screen, so one can be created, scheduled, paused, resumed and cancelled from code — and by an AI agent, if you have granted it that. Drafting a campaign and sending one are **separate permissions**: `campaigns:write` builds it, `campaigns:send` puts it in people's inboxes. That split is what makes it safe to let an agent prepare a campaign for you. Every send is checked against your [suppression list](/glossary/suppression-list) as it goes out, so an address that unsubscribed after the segment was evaluated is still skipped. Per-campaign stats — delivered, bounced, opened, clicked, complained — are available in the dashboard and through the API. See [Campaigns](/concepts/campaigns). --- # Workflow (/glossary/workflow) A **workflow** is an automation: a trigger, then a sequence of steps that runs for each contact who enters it. Wait three days. If they have not opened anything, send this. If they have, send that instead. Others call the same idea a journey, an automation, or a drip. The difference from a [campaign](/glossary/campaign) is time and cardinality. A campaign is one send to many people at one moment. A workflow is a path each person walks separately, starting whenever they qualify. ## What can trigger one [#what-can-trigger-one] - A contact joining a list or matching a [segment](/glossary/segment). - A tracked event recorded from your own product — a plan change, an abandoned setup, a feature used for the first time. - A change to a contact's own fields. ## The thing to be careful about [#the-thing-to-be-careful-about] A workflow keeps sending on its own, long after whoever enabled it stopped thinking about it. That is the whole value and also the whole risk: an enabled workflow with a mistake in it makes that mistake repeatedly, to everyone who enters. Sendly treats it accordingly. `workflows:write` is one of the eight permissions that arrive **unchecked** on an AI agent's consent screen, with the consequence stated — see [the MCP guide](/guides/mcp). ## In Sendly [#in-sendly] Workflows are built in a visual builder and run server-side, with a per-contact execution log so you can see which branch someone took and why. They are also a full API object, so one can be created, cloned, paused, resumed and inspected from code. See [Workflows](/concepts/workflows) and [Event tracking](/guides/tracking). --- # Segment (/glossary/segment) A **segment** is a set of contacts defined by a rule instead of by membership: everyone in Germany who has opened something in the last ninety days, everyone on a trial that ends this week, everyone who has never clicked anything. The rule is the definition, so the membership is always current. Nobody has to remember to add or remove anyone, which is the difference between a segment and a static list. ## Why it matters beyond convenience [#why-it-matters-beyond-convenience] Sending less mail to more relevant people beats sending more mail to everyone, and it does so on the metric that decides whether your mail arrives at all. Engagement is a positive [reputation](/glossary/sender-reputation) signal; a large audience that never opens anything is a negative one, even with no [complaints](/glossary/complaint). Excluding your unengaged contacts from a broadcast is usually the single cheapest deliverability improvement available. ## In Sendly [#in-sendly] Segments are built from contact fields, custom fields, list membership and tracked behaviour, and are re-evaluated rather than snapshotted. A [campaign](/glossary/campaign) can be aimed at one, a [workflow](/glossary/workflow) can be triggered by entry into one, and the API can page through a segment's contacts with cursor pagination — which matters when the answer is a few million rows. See [Segments](/concepts/segments) and [Contacts](/concepts/contacts). --- # Template variable (/glossary/template-variable) A **template variable** is a placeholder in a template that is replaced with a value for each recipient when the message is rendered — a first name, a plan name, an order total, an expiry date. Other tools call the same thing a merge field or a merge tag. Variables are what make one template into a hundred thousand personalised messages, and they are the reason a template is worth having at all rather than assembling markup in your application. ## Two failure modes worth designing for [#two-failure-modes-worth-designing-for] **A missing value.** If half your contacts have no first name, `Hi {{first_name}},` renders as `Hi ,` for them. Decide what an absent value should produce before you send, not after — a sensible default is usually better than an awkward greeting. **Untrusted content.** A variable whose value came from a user is content you did not write, rendered into markup. Sendly escapes variable values at the render boundary so a value cannot inject markup into the message, but the general principle is worth carrying into your own templates too. ## In Sendly [#in-sendly] Templates are a reusable object with their own API, and a variable's value comes from the contact's fields or from data supplied with the send. A template may also supply the From address, which is why the send receipt reports the sender actually used rather than assuming it was the one you passed. Sandbox test sends let you check a render against real data without mailing anyone. See [Templates](/concepts/templates). --- # Idempotency key (/glossary/idempotency-key) An **idempotency key** is a string you attach to a request so that retrying it cannot repeat its effect. The first request wins; a retry carrying the same key gets the original result back instead of doing the work again. It exists because of one specific, common failure: your request reaches the server, the server sends the email, and the response is lost on the way back. Your code sees a timeout and cannot tell that from the request never arriving. Without a key, the safe-looking choice — retry — mails the customer twice. ## How to choose one [#how-to-choose-one] Derive it from the thing the message is about, not from the moment of sending. An order id, an invoice id, a `password-reset--` — something that is stable across retries because it identifies the same logical message. A random value per attempt is worse than none: it looks like a safeguard and prevents nothing. ## In Sendly [#in-sendly] Pass `Idempotency-Key` on a send. Keys are 1 to 255 characters and are remembered for 24 hours. A retry carrying the same key **and the same body** replays the original receipt. Reusing a key with a *different* body answers `422` rather than serving another request's result — which is the right outcome, because that combination means a bug rather than a retry. The header works on the native send and through the Plunk compat endpoint. See the [send API](/api-reference/emails/v1SendEmail). --- # Webhook (/glossary/webhook) A **webhook** is a reversal of the usual direction: rather than your code polling an API to ask whether anything has happened, you register a URL and Sendly POSTs to it when something does — a message delivered, [bounced](/glossary/bounce), opened, clicked, or [complained](/glossary/complaint) about. It is how a delivery record in Sendly becomes a state change in your own system: marking a contact, alerting a support queue, or stopping a dunning sequence when the invoice is finally paid. ## The three things every webhook consumer needs [#the-three-things-every-webhook-consumer-needs] - **Verify the signature.** An endpoint that accepts any POST is an endpoint anybody can forge events into. Sendly signs deliveries; check the signature before you trust the body. - **Be idempotent.** Retries mean the same event can arrive twice. Key your handling on the event id so processing it a second time changes nothing. - **Answer quickly.** Acknowledge with a 2xx and do the work afterwards. An endpoint that takes ten seconds to reply looks like an endpoint that is down. ## Ordering [#ordering] Do not assume events arrive in the order they happened. Deliveries and retries interleave. Use the timestamp on the event rather than arrival order when the sequence matters. ## In Sendly [#in-sendly] Webhooks are configured per project, deliveries are signed and retried on failure, and the same events are also queryable through the events API — so a webhook you missed during an outage is not information you have lost. See the [webhooks guide](/guides/webhooks). --- # Open tracking (/glossary/open-tracking) **Open tracking** works by embedding a tiny transparent image in the HTML of a message. When a mail client loads that image from the server, the request is recorded as an open. That mechanism explains everything odd about the number. ## Why it undercounts [#why-it-undercounts] A client that blocks remote images records no open, and blocking is the default in a great many of them. Someone who read your message carefully in a plain-text client is invisible. ## Why it also overcounts [#why-it-also-overcounts] Apple Mail Privacy Protection and similar features **pre-fetch** images for messages the user has not opened, which registers an open that never happened. Corporate security scanners do the same when they follow links and load resources. So the number is neither a count nor an estimate. It is most useful as a **relative** measure — this subject line against that one, to the same audience, in the same week — and close to meaningless as an absolute. Clicks are the sturdier signal. A click needs a deliberate act, and it is not manufactured by a privacy proxy. ## In Sendly [#in-sendly] Opens and clicks are recorded as events, visible per campaign and available through the API and [webhooks](/glossary/webhook). Because an open is a request for an image, tracking requires an HTML body — a plain-text message cannot be tracked, by anyone, ever. Engagement still matters for [deliverability](/glossary/deliverability) even when you cannot measure it precisely, which is the argument for acting on the trend rather than the figure. See [Tracking](/guides/tracking). --- # Model Context Protocol (/glossary/model-context-protocol) The **Model Context Protocol** (MCP) is an open standard for connecting AI agents to systems they can act in. A server exposes a set of **tools** — named operations with typed arguments — and any MCP-capable client can discover them and call them on the user's behalf. Sendly runs a remote MCP server, so an agent can answer which of your domains are verified, tidy your contacts, diagnose why a message did not arrive, build and pause your [workflows](/glossary/workflow), draft your next campaign, and — if you say so — send it. ## The endpoint [#the-endpoint] ``` https://app.sendly.now/api/mcp ``` The transport is Streamable HTTP. Authorization is OAuth 2.1 with PKCE, or a Sendly secret key on the `Authorization` header. Dynamic client registration is open and the protected-resource and authorization-server metadata documents are published at their conventional well-known URLs, so a client that has never spoken to Sendly can discover what it needs and start the flow unattended. ## What makes it safe to use [#what-makes-it-safe-to-use] The tools an agent can see are decided **before it asks**, by filtering the registry against the credential's own permissions. A tool outside the grant is never registered, so the agent does not know it exists rather than being refused when it tries. Eight permissions produce effects nothing in Sendly undoes — sending mail, sending a [campaign](/glossary/campaign), enabling a [workflow](/glossary/workflow), removing a [suppression](/glossary/suppression-list), and four more. Those arrive **unchecked** on the consent screen, each with a sentence naming the consequence. Drafting a campaign and sending one are separate permissions, which is what lets an agent be genuinely useful without being able to mail your whole audience. One check is enforced by Sendly rather than by your client: in a project with more than 1,000 contacts, sending a campaign is refused the first time and has to be repeated with an explicit confirmation argument. A stateless server cannot ask a person anything mid-call, so the confirmation is something it can demand instead of something it has to request. See [the MCP guide](/guides/mcp) for the full tool list and the consent walkthrough. --- # Migrate from another provider (/migrate) Sendly speaks the transactional-send dialect of several popular email providers. If you already send through Resend, SendGrid, Postmark, Mailgun, or Plunk, you don't have to rewrite your integration or adopt a new SDK to try Sendly — keep the vendor SDK you already run and change **two things**: 1. the **base URL** (or host) the SDK points at, and 2. the **API key** (use a Sendly secret key — see [API Keys](/guides/api-keys)). Everything else — templates, domains, suppression, tracking — you configure in the Sendly UI. Point the resend SDK (JS or Python) at Sendly. Point @sendgrid/mail (JS) or sendgrid (Python) at Sendly. Point the postmark SDK at Sendly with a request-host override. Point mailgun.js at Sendly with a URL override. Sendly's ancestral API — a near drop-in for existing Plunk senders. ## How the compatibility layer works [#how-the-compatibility-layer-works] Each provider gets a dedicated **compat endpoint** under `{{API_URL}}/api/compat/`. These endpoints are thin translators: they parse the vendor's request shape, map it onto Sendly's native send, and run it through the **same pipeline** your native API calls use. That means every Sendly gate still applies — verified-domain checks, sending limits, suppression, and billing — regardless of which dialect you send in. The compat endpoints cover the **transactional send path** only. For the full Sendly surface — contacts, campaigns, workflows, templates, webhooks — use the official [Sendly SDKs](/sdks) or the [API](/api-reference/overview) directly. ## What happens to features Sendly can't map [#what-happens-to-features-sendly-cant-map] A dialect can express things Sendly doesn't support in this phase (scheduled sends, dynamic templates, URL-fetched attachments, and so on). Rather than silently dropping them, the compat endpoint returns a **clean error in that vendor's own error shape** — so your existing SDK's error handling fires exactly as it would against the original provider. Each provider page below lists precisely what is supported and what returns an error. ## Getting a Sendly key [#getting-a-sendly-key] Every request authenticates with a Sendly **secret key** (`sk_...`) for a project that has at least one [verified sending domain](/guides/verifying-domains). Create one in your project settings; it slots into the same place the vendor's own key went. A key with full permissions works across every compat endpoint. If you ticked specific permissions when you created the key, the compat endpoints enforce them exactly as the native API does: sending needs `emails:send`, and reading a message back — Resend's `emails.get()`, the one compat call that is not a send — needs `emails:read`. Reading returns the message's subject, body and recipient, so it follows the same permission rule here as it does natively. A send-only key gets a **403 in that vendor's own error shape**, with the message naming the permission it is missing. --- # Migrate from Resend to Sendly (/migrate/resend) Sendly implements Resend's `POST /emails`, `POST /emails/batch`, and `GET /emails/:id` endpoints. Keep the official `resend` SDK — change the **base URL** and the **API key**. - **Base URL:** `{{API_URL}}/api/compat/resend` - **Auth:** `Authorization: Bearer ` (the SDK sets this for you) No Sendly key yet? [Create a free account]({{DASHBOARD_URL}}/auth/signup), verify a [sending domain](/guides/verifying-domains), then create a key in your project's API key settings. Still deciding? [Sendly vs Resend](https://sendly.now/vs/resend) compares the two products, [migrating from Resend](https://sendly.now/migrate/resend) answers the questions teams ask before switching, and the [staged rollout plan](https://sendly.now/migrate) covers moving traffic over in steps. ## The two-variable swap [#the-two-variable-swap] ```js title="Before (Resend)" import { Resend } from "resend"; const resend = new Resend("re_your_resend_key"); await resend.emails.send({ from: "you@yourdomain.com", to: "customer@example.com", subject: "Hello", html: "

    Welcome aboard.

    ", }); ``` ```js title="After (Sendly)" import { Resend } from "resend"; const resend = new Resend("sk_your_sendly_key", { baseUrl: "{{API_URL}}/api/compat/resend", }); await resend.emails.send({ from: "you@yourdomain.com", to: "customer@example.com", subject: "Hello", html: "

    Welcome aboard.

    ", }); ``` The SDK also honors the `RESEND_BASE_URL` environment variable, so you can point it at Sendly without touching code: ```bash RESEND_BASE_URL="{{API_URL}}/api/compat/resend" ```
    ```python title="Before (Resend)" import resend resend.api_key = "re_your_resend_key" resend.Emails.send({ "from": "you@yourdomain.com", "to": "customer@example.com", "subject": "Hello", "html": "

    Welcome aboard.

    ", }) ``` ```python title="After (Sendly)" import resend resend.api_key = "sk_your_sendly_key" resend.api_url = "{{API_URL}}/api/compat/resend" resend.Emails.send({ "from": "you@yourdomain.com", "to": "customer@example.com", "subject": "Hello", "html": "

    Welcome aboard.

    ", }) ``` The Python SDK also reads the `RESEND_API_URL` environment variable.
    ## API reference [#api-reference] Resend's dialect is documented operation by operation, with the request and response schemas Sendly accepts and returns: - [Send an email (`POST /emails`)](/api-reference/compatibility/compatResendSendEmail) - [Send a batch (`POST /emails/batch`)](/api-reference/compatibility/compatResendSendBatch) - [Retrieve an email (`GET /emails/{id}`)](/api-reference/compatibility/compatResendGetEmail) ## Supported fields [#supported-fields] | Field | Support | Notes | | --- | --- | --- | | `from` | Full | Plain address or `"Name "` display-name form. | | `to` | Full | String or array. | | `cc` / `bcc` | Full | String or array. Each copied address receives the message. A send naming several `to` addresses is one message per `to`; the copies are stored on and delivered with the first one only, so `GET /emails/{id}` answers `cc` and `bcc` as `null` for every row. A message with copies cannot use `{{unsubscribeUrl}}`, `{{subscribeUrl}}`, `{{manageUrl}}` or `{{id}}` (`422`). | | `subject` | Full | | | `html` / `text` | Full | `html` is preferred when both are present. At least one is required. | | `reply_to` | Partial | The first address is used. | | `headers` | Full | | | `attachments` | Partial | Inline base64 `content` only (see below). | | `tags` | Partial | Best-effort: `name`/`value` are combined and sanitized, max 10. | | `emails.get(id)` | Full | Returns the Resend email object with a mapped `last_event`. Needs a key with `emails:read` — see below. | | Batch send | Full | Order is preserved in the response. Up to 100 emails per request; a longer array is refused with `422` `validation_error` and nothing is sent. | ## Not supported (returns a clean Resend error) [#not-supported-returns-a-clean-resend-error] | Field | Result | | --- | --- | | `scheduled_at` | `422 validation_error` — scheduled sends aren't supported in this phase. | | `attachments[].path` | `422` — Sendly does not fetch attachments from a URL; send the file inline as base64 `content`. | | `template` | `422` — Resend template IDs can't be mapped to Sendly templates. | | `topic_id` | `422` — broadcast topics aren't supported. | Each unsupported field returns Resend's own `{ statusCode, message, name }` error body, so your existing `resend` error handling (`{ data, error }` in JS, a raised `ResendError` in Python) behaves exactly as it does today. ## Key permissions [#key-permissions] Sending works with any key that may send. `emails.get(id)` is the one Resend call Sendly maps to something other than a send, and it is gated on `emails:read` instead — reading returns the message's subject, body and recipient, so it follows the same permission rule here as it does on the native API. A key with full permissions covers both and needs nothing changed. A key created with only sending ticked keeps sending normally and gets this on the read: ```json { "statusCode": 403, "message": "This API key is missing the required scope: emails:read", "name": "restricted_api_key" } ``` Grant the key `emails:read` in your project's API key settings, or use a full-permission key. --- # Migrate from SendGrid (/migrate/sendgrid) Sendly implements SendGrid's `POST /v3/mail/send`. Keep the official `@sendgrid/mail` (JavaScript) or `sendgrid` (Python) SDK — change the **base URL / host** and the **API key**. - **Base URL / host:** `{{API_URL}}/api/compat/sendgrid` - **Auth:** `Authorization: Bearer ` (the SDK sets this for you) - **Success response:** `202` with an empty body and an `X-Message-Id` header — the exact semantic `@sendgrid/mail` expects. ## The two-variable swap [#the-two-variable-swap] The transport's base URL is set on `@sendgrid/client`, which `@sendgrid/mail` then uses. `setApiKey` resets the base URL, so set the base URL **after** it. ```js title="Before (SendGrid)" import sgMail from "@sendgrid/mail"; sgMail.setApiKey("SG.your_sendgrid_key"); await sgMail.send({ to: "customer@example.com", from: "you@yourdomain.com", subject: "Hello", html: "

    Welcome aboard.

    ", }); ``` ```js title="After (Sendly)" import sgMail from "@sendgrid/mail"; import sgClient from "@sendgrid/client"; sgClient.setApiKey("sk_your_sendly_key"); sgClient.setDefaultRequest("baseUrl", "{{API_URL}}/api/compat/sendgrid"); sgMail.setClient(sgClient); await sgMail.send({ to: "customer@example.com", from: "you@yourdomain.com", subject: "Hello", html: "

    Welcome aboard.

    ", }); ```
    ```python title="Before (SendGrid)" from sendgrid import SendGridAPIClient from sendgrid.helpers.mail import Mail message = Mail( from_email="you@yourdomain.com", to_emails="customer@example.com", subject="Hello", html_content="

    Welcome aboard.

    ", ) SendGridAPIClient("SG.your_sendgrid_key").send(message) ``` ```python title="After (Sendly)" from sendgrid import SendGridAPIClient from sendgrid.helpers.mail import Mail message = Mail( from_email="you@yourdomain.com", to_emails="customer@example.com", subject="Hello", html_content="

    Welcome aboard.

    ", ) client = SendGridAPIClient( api_key="sk_your_sendly_key", host="{{API_URL}}/api/compat/sendgrid", ) client.send(message) ```
    ## API reference [#api-reference] The one operation this dialect covers, with its full request and response schema: - [Send mail (`POST /v3/mail/send`)](/api-reference/compatibility/compatSendgridSendMail) ## Supported fields [#supported-fields] | Field | Support | Notes | | --- | --- | --- | | `personalizations[]` | Full | Each personalization fans out into its own send (its `to`/`cc`/`bcc` + subject). Up to 100 per request; more is refused with `400` and nothing is sent. Sendly caps `to` + `cc` + `bcc` at 50 recipients per personalization (SendGrid allows 1,000 per request), so split larger sends into a batch or several requests. | | `content[]` | Full | The `text/html` entry is preferred as the body, else `text/plain`. | | `from` / `reply_to` | Full | `{ email, name }` objects. | | `subject` | Full | Top-level or per-personalization. | | `attachments` | Full | `type` maps to content type, `content_id` to the inline content ID. | | `categories` | Partial | Mapped to Sendly tags (sanitized). | | `headers` | Full | | ## Not supported (returns a clean SendGrid error) [#not-supported-returns-a-clean-sendgrid-error] | Field | Result | | --- | --- | | `template_id` (`d-...` dynamic templates) | `400` — SendGrid template IDs can't be mapped to Sendly templates. | | `send_at` | `400` — scheduled sends aren't supported in this phase. | Errors come back in SendGrid's `{ "errors": [{ "message", "field", "help" }] }` shape with the matching status, so the SDK's own error handling — a thrown `ResponseError` in JavaScript, an `HTTPError` in Python — fires exactly as it does today. --- # Migrate from Postmark (/migrate/postmark) Sendly implements Postmark's `POST /email` and `POST /email/batch`. Keep the official `postmark` (Node) SDK — change the **request host** and the **server token**. - **Base URL:** `{{API_URL}}/api/compat/postmark` - **Auth:** `X-Postmark-Server-Token: ` — Postmark's header auth style; the SDK sets this from the token you pass. Use a Sendly secret key as the token. Postmark does not publish an official Python SDK. Python senders can use the Node SDK, call the compat endpoint over plain HTTP, or use the [Sendly Python SDK](/sdks). ## The two-variable swap [#the-two-variable-swap] The Postmark Node client takes a `requestHost` (host **plus path**, without the scheme) and a `useHttps` flag, so the dialect prefix hangs off the host: ```js title="Before (Postmark)" import * as postmark from "postmark"; const client = new postmark.ServerClient("your-postmark-server-token"); await client.sendEmail({ From: "you@yourdomain.com", To: "customer@example.com", Subject: "Hello", HtmlBody: "

    Welcome aboard.

    ", }); ``` ```js title="After (Sendly)" import * as postmark from "postmark"; const client = new postmark.ServerClient("sk_your_sendly_key", { useHttps: true, requestHost: "api.sendly.now/api/compat/postmark", }); await client.sendEmail({ From: "you@yourdomain.com", To: "customer@example.com", Subject: "Hello", HtmlBody: "

    Welcome aboard.

    ", }); ``` ## API reference [#api-reference] Postmark's two send operations, with their full request and response schemas: - [Send a single email (`POST /email`)](/api-reference/compatibility/compatPostmarkSendEmail) - [Send a batch (`POST /email/batch`)](/api-reference/compatibility/compatPostmarkSendBatch) ## Supported fields [#supported-fields] | Field | Support | Notes | | --- | --- | --- | | `From` | Full | Plain address or `"Name "` form. | | `To` / `Cc` / `Bcc` | Full | Comma-separated recipient lists, as Postmark sends them. | | `Subject` | Full | | | `HtmlBody` / `TextBody` | Full | `HtmlBody` is preferred when both are present. At least one is required. | | `ReplyTo` | Full | | | `Headers` | Full | `[{ Name, Value }]`. | | `Attachments` | Full | `[{ Name, Content, ContentType, ContentID }]`. | | `Tag` | Partial | Single tag, sanitized. | | `MessageStream`, `TrackOpens`, `TrackLinks` | Accepted | Accepted and ignored. | | `POST /email/batch` | Full | Returns an array of results, order preserved. Up to 100 messages per request; a longer array is refused with `422` (`ErrorCode` 300) and nothing is sent. | Success comes back in Postmark's shape: `{ To, SubmittedAt, MessageID, ErrorCode: 0, Message }`. ## Not supported (returns a clean Postmark error) [#not-supported-returns-a-clean-postmark-error] Template sends (`sendEmailWithTemplate` / `TemplateId` / `TemplateModel`) aren't implemented in this phase. Anything Sendly can't map returns Postmark's `{ ErrorCode, Message }` error body with the matching status (for example a bad token is `401` with `ErrorCode: 10`), so the SDK's own error classes — `InvalidAPIKeyError`, `ApiInputError`, and friends — are thrown exactly as they are today. --- # Migrate from Mailgun (/migrate/mailgun) Sendly implements Mailgun's `POST /v3//messages`. Keep the official `mailgun.js` SDK — change the **URL** and the **API key**. - **Base URL:** `{{API_URL}}/api/compat/mailgun` (the SDK appends `/v3//messages`) - **Auth:** HTTP Basic `api:` — Mailgun's basic-auth style, where the username is the literal `api` and the password is your key. Use a Sendly secret key as the key. Mailgun does not publish an official Python SDK. Python senders can call the compat endpoint over plain HTTP (`multipart/form-data`) or use the [Sendly Python SDK](/sdks). ## The two-variable swap [#the-two-variable-swap] ```js title="Before (Mailgun)" import formData from "form-data"; import Mailgun from "mailgun.js"; const mailgun = new Mailgun(formData); const mg = mailgun.client({ username: "api", key: "your-mailgun-key" }); await mg.messages.create("yourdomain.com", { from: "you@yourdomain.com", to: "customer@example.com", subject: "Hello", html: "

    Welcome aboard.

    ", }); ``` ```js title="After (Sendly)" import formData from "form-data"; import Mailgun from "mailgun.js"; const mailgun = new Mailgun(formData); const mg = mailgun.client({ username: "api", key: "sk_your_sendly_key", url: "{{API_URL}}/api/compat/mailgun", }); await mg.messages.create("yourdomain.com", { from: "you@yourdomain.com", to: "customer@example.com", subject: "Hello", html: "

    Welcome aboard.

    ", }); ``` The domain in the URL path (`yourdomain.com` above) **must match** the domain of your `from` address. A mismatch returns a `400` in Mailgun's error shape. ## API reference [#api-reference] The one operation this dialect covers, with its full request and response schema: - [Send a message (`POST /v3/{domain}/messages`)](/api-reference/compatibility/compatMailgunSendMessage) ## Supported fields [#supported-fields] | Field | Support | Notes | | --- | --- | --- | | `from` | Full | Must be on a [verified domain](/guides/verifying-domains) that matches the URL path. | | `to` | Full | Repeatable, as Mailgun sends it. Sendly caps `to` + `cc` + `bcc` at 50 recipients per request (Mailgun allows 1,000), so split larger sends into a batch or several requests. | | `cc` / `bcc` | Full | Count toward the same 50-recipient cap as `to`. | | `subject` | Full | | | `html` / `text` | Full | `html` is preferred when both are present. At least one is required. | | `h:X-*` headers | Full | The `h:` prefix is stripped. | | `o:tag` | Partial | Repeatable; mapped to Sendly tags (sanitized). | | `attachment` | Full | File parts are read and attached. | Success comes back in Mailgun's shape: `{ "id": "", "message": "Queued. Thank you." }`. ## Not supported [#not-supported] Mailgun options beyond `o:tag` — scheduled delivery (`o:deliverytime`), tracking toggles, and stored templates — are **not applied**; only the fields in the table above are honored. Auth, validation, and domain-match failures return Mailgun's bare `{ "message": ... }` error body with the matching status (a bad key is `401`), so `mailgun.js`'s own error handling (`error.status` / `error.details`) fires as it does today. --- # Migrate from Plunk (/migrate/plunk) Plunk's transactional send is Sendly's ancestral shape, so `POST /v1/send` is a **near passthrough**. Change the **base URL** and the **API key** and your existing Plunk send calls keep working. - **Endpoint:** `{{API_URL}}/api/compat/plunk/v1/send` - **Auth:** `Authorization: Bearer ` ## The two-variable swap [#the-two-variable-swap] The request and response bodies are unchanged — only the URL and key move: ```js title="Before (Plunk)" await fetch("https://api.useplunk.com/v1/send", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer your-plunk-secret-key", }, body: JSON.stringify({ to: "customer@example.com", subject: "Hello", body: "

    Welcome aboard.

    ", }), }); ``` ```js title="After (Sendly)" await fetch("{{API_URL}}/api/compat/plunk/v1/send", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer sk_your_sendly_key", }, body: JSON.stringify({ to: "customer@example.com", subject: "Hello", body: "

    Welcome aboard.

    ", }), }); ``` ## API reference [#api-reference] The one operation this dialect covers, with its full request and response schema: - [Send an email (`POST /v1/send`)](/api-reference/compatibility/compatPlunkSendEmail) ## Supported fields [#supported-fields] | Field | Support | Notes | | --- | --- | --- | | `to` | Full | String or array. | | `subject` | Full | | | `body` | Full | HTML or plain text. | | `Idempotency-Key` header | Full | 1–255 characters; safely retries a send. | The response mirrors Plunk's native shape: `{ "success": true, "emails": [...], "timestamp": ... }`. Because Plunk and Sendly share this send shape, most Plunk integrations migrate with only the URL and key change. For everything beyond transactional sending, use the official [Sendly SDKs](/sdks) or the [API](/api-reference/overview). ## Errors [#errors] Failures come back in Plunk's `{ code, error, message, time }` shape with the matching status, so a client reading `body.message` or `body.error` behaves unchanged. --- # Trust (/trust) An email platform asks for two unusual things: your list, and permission to send as you. This section is what we commit to in return, written to be checked rather than believed. Each page below describes what the platform actually does. Where a behaviour is blunt or one-sided, it says so on the page rather than in the terms. ## The commitments [#the-commitments] ### You can leave with everything, at any time [#you-can-leave-with-everything-at-any-time] The whole account — contacts, templates, campaigns, segments, suppressions, events — in an open format, from the dashboard, without asking anyone. Including while a project is stopped. → [Portability and pricing commitments](/trust/portability) ### You will not be surprised by a price change [#you-will-not-be-surprised-by-a-price-change] Thirty days' notice by email before any increase, your current price through the end of the period you are in, and no mid-term repricing. → [Portability and pricing commitments](/trust/portability) ### The limits are published, and so are their edges [#the-limits-are-published-and-so-are-their-edges] Where the bounce and complaint bands sit, what happens at each one, and — this is the part usually left out — exactly which of those events reach your inbox and which only reach our operations team. → [Sending standards](/security) ### Enforcement is fast, and the way back is answered by a person [#enforcement-is-fast-and-the-way-back-is-answered-by-a-person] A project can be stopped with no warning. That is only defensible if the appeal is quick, so we commit to a first response from a person within 24 hours, and a stopped project stays fully readable and exportable while you wait. → [Appeals](/appeals) ## What we deliberately do not do [#what-we-deliberately-do-not-do] Stated here so it is not a surprise later: - **We do not warn you by email before stopping a project.** There is a flagged stage for bounces and complaints, but it appears in your dashboard and pages our team — nothing arrives in your inbox. For content violations there is no flagged stage at all. - **We do not publish the content-scanning thresholds.** Publishing them turns a safety limit into a budget for whoever is abusing the platform. - **We do not explain a content decision in detail.** You get the decision, not the score or the rule. - **We do not un-disable a project automatically.** A person decides. [Sending standards](/security) explains the reasoning behind each of these. ## Security and privacy [#security-and-privacy] - Report a vulnerability: security@sendly.now. Good-faith research is welcome and we will not pursue you for it — see [acceptable use](/security/acceptable-use). - What we collect and why: the [privacy policy](https://sendly.now/privacy). - Everything else: support@sendly.now. We answer our own email. --- # Portability and pricing commitments (/trust/portability) Two promises, both of which cost us something. That is what makes them worth writing down. ## You can take everything, at any time [#you-can-take-everything-at-any-time] Not "contact your account manager". Not a CSV of contacts and nothing else. The whole account, on demand, from the dashboard. ### What is in the export [#what-is-in-the-export] | Included | Not included | | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | Your account profile | Your password (we never hold a reversible copy) | | Every project you own | API key secrets and webhook signing secrets — the metadata is there, the credentials are not | | Contacts, with their custom fields and subscription state | Other people's projects that you are a member of but do not own | | Lists, segments, templates and campaigns | | | Suppressions — the bounce and complaint record that keeps you out of trouble elsewhere | | | Events | | | Sending domains, API key metadata and webhook configuration | | Credentials are left out on purpose: the export is a file you download over the network, and a live signing secret in it would be a worse risk to you than the inconvenience of re-issuing one. ### How to get it [#how-to-get-it] **Settings → Data**, "Export account data". It runs in the background — an account with millions of contacts is not something a web request can produce — and the page shows you when it is ready. Or over the API, signed in: ```http POST /api/users/me/exports # start one GET /api/users/me/exports # status and history GET /api/users/me/exports/{id}/download ``` One export per hour per account. ### The format [#the-format] A single gzipped [NDJSON](https://github.com/ndjson/ndjson-spec) file: one JSON object per line, readable with standard tools and streamable without loading it into memory. ```sh gzip -dc sendly-export-*.ndjson.gz | head -1 # the manifest gzip -dc sendly-export-*.ndjson.gz | jq -c 'select(.dataset == "contacts") | .data' ``` The first line is a manifest naming every dataset in the file, so you can tell a complete archive from a truncated one. ### How long the link lasts [#how-long-the-link-lasts] The download works for **72 hours**, then the archive is deleted from our storage. The link is not a public URL — it only works while you are signed in as the account that requested it, so forwarding it to someone does not give them your contact list. Request another one whenever you like. ### While a project is stopped [#while-a-project-is-stopped] Export still works. A disabled project stays fully readable precisely so that this remains true — see [appeals](/appeals). ### Deleting instead [#deleting-instead] **Settings → Data**, "Delete account", and confirm by typing your email address. This signs you out and pauses the projects you own at once, and deletes your account and those projects 30 days later. Signing in again within the 30 days cancels the deletion and resumes your projects. After that it is not reversible, so export first if you want a copy. ## You will not be surprised by a price change [#you-will-not-be-surprised-by-a-price-change] - **30 days' notice, by email, before any price increase takes effect.** Not a changelog entry, not a banner you might not see. - **Your current price holds through the end of the billing period you are in** when the change lands. - **No mid-term repricing.** A price you signed up at is not adjusted retroactively. - **If a change does not work for you, leave with everything.** The export above is the same one you would use on any other day, it does not require an active subscription, and we will not slow it down or hold data back while a subscription is winding down. Details of what you pay are on the [billing](/concepts/billing) page. This page is about what happens when that changes. ## No lock-in, concretely [#no-lock-in-concretely] Lock-in is usually not a policy — it is a set of small frictions. Ours, and where they are not: - **Your data leaves in an open format.** NDJSON, documented above, no proprietary container. - **Your integration is not proprietary either.** The API is a published OpenAPI document and the SDKs are open source. Migrating away is rewriting a client, not reverse engineering one. - **Your suppression list comes with you.** It is the piece most platforms quietly keep, and the piece that protects your sender reputation somewhere else. - **No exit fee, no notice period to cancel, no minimum term.** ## Related [#related] - [Sending standards](/security) — the limits, and what happens at each one. - [Appeals](/appeals) — if a project has been stopped. - [Billing](/concepts/billing) — what you pay and how it is measured. --- # Sending standards (/security) Sendly sends your mail through shared infrastructure. One sender with a bad list can damage delivery for everyone on it, so there are limits, and crossing them can stop your project from sending. This page says exactly where those limits are and what happens at each one. It describes what the platform actually does today, including the parts that are blunt. ## Two different systems, two different behaviours [#two-different-systems-two-different-behaviours] They are worth separating, because they treat you very differently. **Reputation** — bounces and spam complaints — is a gradual, measured signal. It has a warning stage, and the numbers are published below. **Content** — mail that scans as phishing — is not gradual. There is no warning stage, the thresholds are not published, and one bad result can stop every project you own. ## Reputation: the published ladder [#reputation-the-published-ladder] Two bands. Crossing the first flags your project. Crossing the second stops it sending. | Signal | Window | Flagged at | Sending stops at | | ------------------- | -------------- | ---------- | ---------------- | | Hard bounce rate | Rolling 7 days | 4% | 7% | | Hard bounce rate | All time | 3% | 6% | | Spam complaint rate | Rolling 7 days | 0.05% | 0.08% | | Spam complaint rate | All time | 0.025% | 0.08% | Neither band applies until a project has sent at least 100 emails, and a project is never stopped on a rate alone — the absolute count has to be meaningful too, so a handful of bounces on a small list cannot trip it. These are deliberately stricter than our upstream provider's. Amazon SES warns at a 5% bounce rate and suspends at 10%; it warns at a 0.1% complaint rate and suspends at 0.5%. Sendly stops a project before that happens, because a suspension at the provider level would take every Sendly customer down with it, and because a sender who reaches those numbers is going to end up in spam folders long before the provider intervenes. There are also absolute ceilings — a flat number of bounces or complaints in 24 hours or 7 days — which catch a high-volume sender whose rate stays low simply because they send a lot. Those numbers are not published, because publishing them would tell someone exactly how much bad mail they can send without tripping anything. New projects have tighter ceilings than established ones. ## What you are actually told, and when [#what-you-are-actually-told-and-when] This is the part most platforms leave vague. Ours, precisely: ### When you are flagged (the first band) [#when-you-are-flagged-the-first-band] - Your project's **Settings → Security** page shows a Warning state, with each metric's band, its rate, and the counts behind it. - Our operations team is paged. - **No email is sent to you.** There is no "you are approaching a limit" notice in your inbox today. If you are not looking at the dashboard, you will not know. We would rather write that down than imply a warning email exists. If you want to catch this early, check Settings → Security, or watch your bounce and complaint rates on your campaign reports. ### When sending stops (the second band) [#when-sending-stops-the-second-band] - The project is disabled. New sends are refused; so is every other change to the project. - **Reading stays open.** You keep full access to the dashboard, your contacts, your campaign history and your reports — deliberately, so you can see what happened, export your data, and appeal. - You get a notification in Sendly and an email to the project's members. - The reason is shown on the Security page. ## Content: what happens with no warning [#content-what-happens-with-no-warning] Outbound mail is sampled and scanned for phishing. New projects are scanned far more heavily than established ones. If a message scans as phishing with high enough confidence — or if enough messages do inside a short window — the project is disabled immediately. There is no flagged stage, no notice first, and no opportunity to correct it before it happens. Three further things are true here, and none of them are accidents: 1. **The reason you are shown is generic.** It reads "A policy violation was detected. Please contact support for more details." It does not name the message, the score or the rule. A precise reason is a debugging tool for whoever is abusing the platform. 2. **It applies to every project you own.** A phishing verdict is treated as a judgement about the account, not about one project, because nothing limits how many projects one signup can create and containing only one of them would contain nothing. 3. **On a very new project, we do not email you about it.** Operators are paged and the dashboard shows it, but the outbound notice is withheld. The notice would travel through Sendly's own sending pipeline, which tells an active abuser they have been caught, in the same second, using our infrastructure. Projects past their first week keep the email. If you are a legitimate sender who has been caught by this, that third point is why the first you may hear of it is a dashboard that has stopped working. We are sorry about it, it is a real cost of the design, and it is why appeals exist and why we answer them fast. ## The thresholds we do not publish [#the-thresholds-we-do-not-publish] The phishing confidence score, how many detections it takes, and the window they are counted over are not on this page and will not be given out. Publishing them would let someone pace their sending to stay just underneath — which converts a safety limit into a budget. We publish the reputation ladder because it is not gameable in the same way: the only way to stay under a 7% bounce rate is to have a list that does not bounce, which is the behaviour we want anyway. ## If your project has been stopped [#if-your-project-has-been-stopped] You can still sign in, read everything, and export it. Two things to do: - [File an appeal](/appeals). A person reads it, and we commit to a first response within 24 hours. - [Export your data](/trust/portability) if you want a copy regardless of the outcome. ## Related [#related] - [Acceptable use](/security/acceptable-use) — what you may and may not send. - [Appeals](/appeals) — the process and the response time we commit to. - [Portability](/trust/portability) — taking everything with you, at any time. --- # Acceptable use (/security/acceptable-use) This policy applies to everything sent through Sendly: transactional mail, campaigns, workflows and API sends alike. It is short on purpose. Every rule here is one we actually enforce, and each says how. ## Consent [#consent] Send only to people who asked to hear from you. That means a real signup, a purchase, or another relationship where the recipient could reasonably expect your mail. It does not mean a purchased list, a scraped list, a rented list, a list from an acquired company that did not include consent, or addresses appended by a third-party service. **How this is enforced.** Mostly by its consequences: bought and scraped lists bounce and draw complaints, and the [sending standards](/security) stop projects that do. Imports are also screened for the shape a purchased list has, and one that scores badly is held rather than imported. ## Content [#content] Do not send: - Phishing, credential harvesting, or mail impersonating another company, service or person. - Malware, or links to it. - Fraud: fake invoices, fake delivery notices, fake account alerts, advance-fee schemes. - Content that is illegal where you or your recipients are. - Harassment, or content targeting a private individual. **How this is enforced.** Outbound mail is sampled and scanned. A phishing verdict stops the project immediately, with no warning stage, and applies to every project you own. The [sending standards](/security) page describes that path in full, including what you are and are not told. ## Unsubscribes and suppression [#unsubscribes-and-suppression] Honour every unsubscribe, and honour it promptly. Sendly maintains a suppression list per project. Addresses that hard-bounce or file a spam complaint are added automatically and stay there. **How this is enforced.** The suppression list is applied at send time, and re-importing a list does not undo it — a contact import cross-checks suppressions and drops the addresses on them rather than resurrecting them. This is not a limitation to work around; it is the single mechanism that keeps a bounced address from being mailed again. ## Identity [#identity] Send as yourself. Use a From address on a domain you control and have verified, do not forge headers, and make it obvious who the mail is from. **How this is enforced.** Sending from a domain requires DNS verification. Unverified sending is limited to a sandbox address with tight caps. ## Volume [#volume] Ramp gradually. A new project has a low daily cap; verifying a domain and subscribing to a paid plan raise it. This protects you as much as us — a sudden first-day blast to a large list is the pattern most likely to land you in spam folders and the pattern abuse looks like. **How this is enforced.** Daily caps are applied per project and per account, so creating more projects does not raise your ceiling. ## Security research [#security-research] If you find a vulnerability in Sendly, tell us at security@sendly.now. We will not pursue you for good-faith research: staying within your own account, not accessing other customers' data, not degrading the service, and giving us reasonable time to fix it. ## Changes to this policy [#changes-to-this-policy] If we change what is allowed in a way that affects what you are already doing, we will tell you before it takes effect. See the [portability and pricing commitments](/trust/portability) for the notice we commit to, and for how to take your data elsewhere if a change does not work for you. ## Reporting abuse [#reporting-abuse] Mail you believe was sent through Sendly in violation of this policy: support@sendly.now. Include full headers if you have them — they are what lets us identify the sender. --- # Appeals (/appeals) If your project has been stopped and you think that was wrong, this is how you say so. The enforcement that stops a project is deliberately fast and deliberately blunt — see [sending standards](/security) for exactly how blunt. That design only defensible if the way back is quick and answered by a person. This page is that commitment, written down so you can hold us to it. ## What you can still do while a project is stopped [#what-you-can-still-do-while-a-project-is-stopped] Everything except send and change things. Reading stays open on a disabled project on purpose. You can sign in, open the dashboard, read your contacts, templates, campaigns, reports and history, see the reason on **Settings → Security**, and [export the whole account](/trust/portability). Nothing is deleted, held hostage, or hidden while an appeal is open. What is refused: sending, and every write to the project — editing a campaign, importing contacts, changing settings. Filing an appeal is the one write that stays available, because it is the one that has to. ## Filing one [#filing-one] In Sendly: **Settings → Security**, on the stopped project. Over the API, as the signed-in owner: ```http POST /api/projects/{projectId}/appeals Content-Type: application/json { "message": "What happened, in your words." } ``` Between 20 and 4000 characters. You must be a member of the project. One appeal per project per 24 hours — a second one inside that window is refused, because it does not reach anyone faster. ## What we commit to [#what-we-commit-to] **A first response from a person within 24 hours** of the appeal being filed. That deadline is stamped onto your appeal when you file it and does not move, even if we later change this page. "First response" means a human has read it and replied — not that the decision is final. A case that needs more from you, or more from us, will say so. ## What we do not promise [#what-we-do-not-promise] We would rather be exact than reassuring. - **Not a reinstatement.** The appeal is read by a person, and a person decides. Some appeals are declined. - **No automatic path back.** Nothing you can do from your own account re-enables a stopped project. That is intentional: an automatic un-disable reachable by the account that was just stopped would undo the containment it is appealing. - **No detailed reason for a content decision.** If the project was stopped by the content scanner, we will not tell you the score, the message, or the rule. A precise explanation is a debugging tool for whoever is abusing the platform. We will tell you the decision. - **No fixed resolution time.** The 24 hours is the first response. A case that needs investigation takes as long as the investigation takes, and we will tell you where it is. ## What helps [#what-helps] An appeal a person can act on in one read: - What the mail was and who asked to receive it. - Where the list came from — a signup form, a purchase, an import, and when. - Anything that changed recently: a new list, a new template, a first campaign, a spike. - If a teammate or an API integration sent something you did not expect, say so. An appeal that only says the decision is wrong gives the reader nothing to check. ## If it was our mistake [#if-it-was-our-mistake] We reinstate the project and say so. False positives happen — the content scanner is tuned to be strict on new accounts, which is exactly the cohort a legitimate new customer is in. That trade-off is ours, not yours, and being caught by it is not held against you. ## Related [#related] - [Sending standards](/security) — what stops a project, and what you are told. - [Acceptable use](/security/acceptable-use) — what is allowed. - [Portability](/trust/portability) — leaving with everything, whatever the outcome. --- # Browser extension privacy policy (/legal/extension-privacy) Effective date: 12 October 2026 This policy covers the **Sendly: Email API Debugger, Delivery Inspector & Domain Health Check** Chrome extension (the "extension"), published by Devino Solutions, which also operates Sendly. It describes every kind of user data the extension handles, why, where it is kept, how long, who it is shared with, and how you delete it. It applies only to the extension; the Sendly service itself is covered by [Sendly's privacy policy](https://sendly.now/privacy). ## The short version [#the-short-version] - The extension keeps two things on your own computer: your Sendly API key and a log of the last 50 API calls it made for you. The log contains the full response text of those calls, which includes real recipient email addresses and subject lines. - It sends your API key to exactly one server, `https://api.sendly.now`, only when you ask it to fetch or send something. That is the whole data flow. - The extension sends API calls only to `api.sendly.now`, which is the Sendly service run by the same publisher, Devino Solutions. The extension itself contains no analytics library, telemetry, crash reporting or advertising. It does open two Sendly pages so that installs and uninstalls can be counted (section 1.5). The Sendly service handles the calls you trigger under Sendly's privacy policy, including a 30-day request log (section 2.1). - We never sell your data and never use it for anything except showing it to you in the extension. It reaches only the Sendly service and the processors named in section 2.1. ## 1. Data the extension handles [#1-data-the-extension-handles] ### 1.1 Your Sendly API key (authentication information) [#11-your-sendly-api-key-authentication-information] - **What:** the API key you paste in, which starts with `sk_`. - **Why:** it is the credential that proves to `api.sendly.now` that a request is yours. Without it the extension cannot read your project. - **Where:** `chrome.storage.local` in your browser profile, on your device. Never `chrome.storage.sync`, so it is not replicated through your Google account or to other devices. - **Shown as:** masked in the interface (first 11 and last 4 characters). - **Never recorded:** it is replaced with `Bearer sk_live_***REDACTED***` before any request is written to the request log, and "Copy as curl" emits the shell variable `$SENDLY_API_KEY` instead of the key. - **Retention:** until you press "Forget key" or uninstall the extension. ### 1.2 The request log (personal communications and personally identifiable information) [#12-the-request-log-personal-communications-and-personally-identifiable-information] - **What:** the last 50 API calls the extension made, newest first. For each one it stores the request line, request headers (with the key redacted), request body, response status, response headers, the **full response body exactly as received**, the time, and the duration. - **What that contains in practice:** the responses are your own Sendly project data, so the log can include recipient email addresses, sender addresses, email subjects and delivery status, delivery-event payloads (bounces, complaints, opens, clicks and their error messages), event records tied to emails and contacts, including any custom event payload your own code recorded, and your sending domains with their DKIM, SPF and MAIL FROM DNS records. When you use "Send test", the log also holds the test message you wrote and the single recipient address (your own verified account address). - **Why:** this log is the extension's purpose. The request inspector shows you the raw request and response behind each call so you can debug your integration. - **Where:** `chrome.storage.local`, on your device only. Never `chrome.storage.sync`. - **Retention:** bounded at 50 entries; the oldest entry is discarded when a new one is added. It stays until you press "Clear" in the Inspector tab or uninstall the extension. ### 1.3 Data displayed but not stored [#13-data-displayed-but-not-stored] The Emails, Events and Domains tabs display what the API returns (the same kinds of data as section 1.2). The displayed lists are held in the popup's memory while it is open and are discarded when it closes. The only copy that persists is the request log in section 1.2, which holds the raw response of each call, not a separate database of your emails. ### 1.4 Interface preference [#14-interface-preference] The light or dark theme you pick is saved by the popup in its own `localStorage` on your device. It contains no personal information. ### 1.5 Install ID, welcome page and goodbye page [#15-install-id-welcome-page-and-goodbye-page] - **What:** a random install ID the extension creates on first install. It is not derived from your account or device. - **Where:** `chrome.storage.local` on your device, never `chrome.storage.sync`. - **How it is used:** right after you install the extension, it opens one welcome page, `app.sendly.now/welcome`, in a new tab. It also tells Chrome to open a goodbye page, `app.sendly.now/goodbye`, if you uninstall it. Both addresses carry the extension's version and the install ID. These are ordinary page visits made by your browser; the extension itself sends nothing. - **What the Sendly service records from those visits:** that the extension was installed or uninstalled, its version and the install ID; if you accepted analytics cookies on sendly.now earlier, how you first found Sendly (the referring site, campaign tags and the first page you landed on); and, if you are signed in to Sendly at the time, your Sendly account ID. Like any page request, the visit also carries your IP address and browser user agent. These records are kept in Sendly's self-hosted product analytics (PostHog). - **Why:** to count installs and uninstalls and to learn which pages or campaigns led people to the extension. - **Retention:** these records are kept until we delete them; we have not set an automatic deletion schedule for them. ### 1.6 What the extension does not handle [#16-what-the-extension-does-not-handle] It does not read the pages you visit or your browsing history, and it requests no `tabs`, `activeTab`, `scripting` or `webRequest` permission and has no content script. It does not collect your name, location, health or financial information, passwords other than the Sendly API key you choose to enter, or any usage statistics apart from the install and uninstall record in section 1.5. ## 2. Where data goes [#2-where-data-goes] **One destination: `https://api.sendly.now`.** This is the only entry in the extension's `host_permissions`, so the browser itself blocks any other destination. Requests are made only when you act (opening a tab, pressing Refresh or Re-check, or pressing Send test), and nothing is sent in the background. Separately, the browser opens the welcome page once after installation and the goodbye page if you uninstall, as described in section 1.5. Neither is a request the extension makes with your API key. | Request | When | | ------------------------------ | ------------------------------------------- | | `GET /api/emails` | You open or refresh the Emails tab | | `GET /api/emails/{id}` | You open one email's delivery timeline | | `GET /api/v1/events` | You open or refresh the Events tab | | `GET /api/domains` | You open or refresh the Domains tab | | `GET /api/domains/{id}/verify` | You press "Re-check" on a domain | | `POST /api/v1/emails/test` | You press "Send test" (a sandbox send only) | Each request carries your API key as a bearer token. The response comes back to your browser and is stored as described in section 1. `api.sendly.now` is operated by Devino Solutions, so the key and these requests are received by the Sendly service, which processes them under [Sendly's privacy policy](https://sendly.now/privacy). ### 2.1 What the Sendly service does with these calls [#21-what-the-sendly-service-does-with-these-calls] - **Request log:** for every API call it records the HTTP method, the route, the response status, the duration, your project, user and API key identifiers, how the call was authenticated, a request identifier, your IP address, your browser's user agent, any error code and message, and the request and response sizes in bytes. It does not record request or response bodies in this log. These rows are deleted automatically after 30 days. - **Send test:** the message is queued as an ordinary email in your Sendly project (kept as your other project emails are, while your account is active) and delivered to your own verified address through Amazon Web Services (SES). For some accounts the subject and body are first checked by an automated content-review classifier that runs through OpenRouter, which routes the request to an underlying AI model provider. The result is used only to block phishing. Reading the Emails, Events and Domains tabs is not scanned. - **Other processors:** the Sendly service runs on Amazon Web Services and self-hosted Devino Solutions infrastructure. Sendly's privacy policy lists all of its subprocessors. ## 3. Use, sharing and sale [#3-use-sharing-and-sale] - **Use:** all data is used only to provide the extension's single purpose: inspecting your own Sendly project's emails, events and domain health and showing the raw API calls behind them. The install and uninstall record in section 1.5 is used only to count installs and uninstalls and to see which pages or campaigns led to them. - **No sale, no sharing:** we do not sell or rent this data, and the extension discloses it to no one except the Sendly service at `api.sendly.now` and the processors named in section 2.1. The extension has no server of its own; the only data the publisher holds is what the Sendly service already holds for your project. - **No advertising or profiling:** it is not used for ads, for determining creditworthiness or for lending, and not transferred for any purpose unrelated to the single purpose. - **Local data stays local:** the extension never uploads its stored copy of your key or request log to the publisher, and no one at the publisher can read that copy, because it exists only in your browser profile. What reaches the Sendly service is handled under Sendly's privacy policy. ## 4. Limited Use [#4-limited-use] The use of information received from Chrome Web Store user data complies with the Chrome Web Store User Data Policy, including its Limited Use requirements. In particular, the extension only uses the data to provide its user-facing single purpose, does not transfer it except as needed for that purpose (the calls to `api.sendly.now` that you trigger), does not use or transfer it for advertising, does not use it to determine creditworthiness or for lending, and does not allow humans to read the data it stores, which leaves your device only in the API calls you trigger. ## 5. Security [#5-security] The extension executes no remote code (its content security policy pins `script-src 'self'`), talks only over HTTPS, and redacts the API key at capture time rather than at display time. Data in `chrome.storage.local` is readable by anyone with access to your browser profile on your device, so use a device and profile you trust, and delete the API key in the Sendly dashboard if a device is lost. Data held by the Sendly service is protected as described in Sendly's privacy policy (encryption in transit and at rest, and access controls). ## 6. Your choices and deleting your data [#6-your-choices-and-deleting-your-data] - **Forget key** removes the API key. - **Clear** in the Inspector tab removes the request log. - **Uninstalling** the extension removes everything it stored, including the theme preference and the install ID. Chrome then opens the goodbye page once. - **Revoke the key** in the Sendly dashboard to make any copy of it useless. **Data held by Sendly.** The controls above remove what the extension stores on your device. To delete data the Sendly service holds (your project's emails and events, and the request logs in section 2.1), email support@sendly.now from your Sendly account address and we will delete it within 30 days, except what the law requires us to keep. Request logs are also deleted automatically after 30 days. ## 7. Children [#7-children] The extension is a developer tool and is not directed at children under 13. ## 8. Changes to this policy [#8-changes-to-this-policy] If the extension ever handles data differently, this policy will be updated before the new version ships, and the effective date above will change. Material changes will be noted in the extension's store listing. ## 9. Contact [#9-contact] Questions or requests: support@sendly.now. Sendly is operated by Devino Solutions, Halifax, Nova Scotia, Canada. ## Verifying any of this [#verifying-any-of-this] The extension is part of the Sendly codebase. The permissions it requests are listed with a justification for each in `apps/extension/wxt.config.ts`, the key and log storage is in `src/lib/credentials.ts` and `src/lib/requestLog.ts`, and a continuous integration check (`scripts/ci/check-extension-manifest.mjs`) fails the build if the packaged extension ever requests a permission, a host or a content script beyond the ones described here. --- # Self-Hosting (/self-hosting/introduction) ## Requirements [#requirements] - Docker and Docker Compose - AWS SES account (for sending emails) - Domain name with subdomains for each service ## Quick Start [#quick-start] 1. Get `docker-compose.prod.yml` from the repository root — it defines the full service graph (web, landing, wiki, the iii engine + worker, Mastra, Postgres, Redis, and Minio). The root `docker-compose.yml` is an intentionally empty placeholder; local dev infra lives in `docker/docker-compose.dev.yml`. 2. Create environment variables with your configuration (see [Environment Variables](/self-hosting/environment-variables)) 3. Run `docker compose -f docker-compose.prod.yml up -d` ## Domain Setup [#domain-setup] Configure these subdomains pointing to your server: | Subdomain | Service | |-----------|---------| | `app.yourdomain.com` | Dashboard | | `api.yourdomain.com` | API | | `docs.yourdomain.com` | Documentation | | `www.yourdomain.com` | Landing page | | `smtp.yourdomain.com` | SMTP relay (optional) | ## Next Steps [#next-steps] - [Docker Deployment](/self-hosting/docker) — Configuration details - [Environment Variables](/self-hosting/environment-variables) — All settings - [AWS SES Setup](/self-hosting/email-setup) — Email configuration --- # Docker Deployment (/self-hosting/docker) ## Quick Start [#quick-start] 1. Copy `docker-compose.prod.yml` from the repository root — it is the source of truth for the deployed service graph. (The root `docker-compose.yml` is an intentionally empty placeholder; local dev infra lives in `docker/docker-compose.dev.yml`.) 2. Configure environment variables 3. Run `docker compose -f docker-compose.prod.yml up -d` The reference compose is oriented for the maintainers' Traefik/Dokploy deploy — it references an external `dokploy-network` and pulls digest-pinned images from GHCR. Adapt the routing labels and image sources for your own environment. ## Minimal .env [#minimal-env] These are the `${VAR}` references the reference compose reads from your environment (see [Environment Variables](/self-hosting/environment-variables) for the complete set the apps validate at boot): ```bash # Secrets DB_PASSWORD="your-secure-password" MINIO_ROOT_PASSWORD="your-minio-password" BETTER_AUTH_SECRET="$(openssl rand -base64 32)" # 32+ chars INTERNAL_SERVICE_TOKEN="$(openssl rand -hex 32)" # Public URLs (point these at your server) BETTER_AUTH_URL="https://app.yourdomain.com" DASHBOARD_URI="https://app.yourdomain.com" LANDING_URI="https://yourdomain.com" WIKI_URI="https://docs.yourdomain.com" # AWS SES AWS_SES_REGION="us-east-1" AWS_SES_ACCESS_KEY_ID="your-key" AWS_SES_SECRET_ACCESS_KEY="your-secret" SES_CONFIGURATION_SET="sendly-tracking" ``` See [Environment Variables](/self-hosting/environment-variables) for all options. ## Services [#services] Each app runs as its own container (the root `Dockerfile` builds one app per image, selected with `--build-arg APP=`): | Container | Purpose | |-----------|---------| | `web` | Dashboard + HTTP API (`APP=web`) — serves the app, api, and tracking hosts | | `landing` | Marketing site (`APP=landing`) | | `wiki` | Documentation site (`APP=wiki`) | | `iii-engine` | Durable event / queue engine (Redis-backed) | | `iii-worker` | Background job worker (`APP=iii`, `SCOPE=iii-worker`) | | `mastra` | AI assistant service (`APP=mastra`) | | `postgres` | PostgreSQL 16 database | | `redis` | Redis 7 (queue + cache) | | `minio` | S3-compatible object storage | | `migrate` | One-shot Prisma migration runner (exits after applying) | ## Ports [#ports] The app containers listen on port 3000 internally and are published through a reverse proxy (Traefik in the reference deploy) rather than bound directly to the host. Minio publishes its API/console; the SMTP ports apply only when the optional mail ingress is enabled. | Port | Service | |------|---------| | 3000 | App containers (internal; proxied) | | 9000 | Minio API | | 9001 | Minio console | | 465 | SMTP implicit TLS (optional) | | 587 | SMTP STARTTLS (optional) | ## Building Individual Apps [#building-individual-apps] There is no runtime `SERVICE` switch — the single root `Dockerfile` builds **one app per image**, selected at build time with the `APP` build arg (`web`, `iii`, `mastra`, `landing`, `wiki`; default `web`), which names the app's directory under `apps/`. A companion `SCOPE` arg selects the workspace package to build and defaults to `APP`; it only differs for the worker, whose directory is `apps/iii` but whose package is `iii-worker` — so that image builds with `APP=iii` and `SCOPE=iii-worker`. Each image then runs as its own container: Pass the matching runner stage with `--target`: `runner-nextjs` for the Next.js apps (`web`, `landing`, `wiki`), `runner-node` for `iii-worker`, and `runner-mastra` for `mastra`. ```bash docker build --build-arg APP=web --target runner-nextjs -t sendly-web . docker build --build-arg APP=iii --build-arg SCOPE=iii-worker --target runner-node -t sendly-iii-worker . docker build --build-arg APP=mastra --target runner-mastra -t sendly-mastra . docker build --build-arg APP=landing --target runner-nextjs -t sendly-landing . docker build --build-arg APP=wiki --target runner-nextjs -t sendly-wiki . ``` ### Sentry source maps (optional) [#sentry-source-maps-optional] Without source maps, a production stack trace in Sentry shows minified frames. If you run your own Sentry, pass your auth token as a **BuildKit secret** and name the release the image is built from: ```bash DOCKER_BUILDKIT=1 SENTRY_AUTH_TOKEN= docker build \ --secret id=SENTRY_AUTH_TOKEN,env=SENTRY_AUTH_TOKEN \ --build-arg SENTRY_ORG= \ --build-arg SENTRY_PROJECT= \ --build-arg SENTRY_RELEASE="$(git rev-parse HEAD)" \ --build-arg SENTRY_URL=https://sentry.example.com \ --build-arg APP=web --target runner-nextjs -t sendly-web . ``` Pass the token as `--secret`, never as `--build-arg`: a build arg is recorded in `docker history` and readable by anyone who can pull the image. `SENTRY_RELEASE` has to be supplied explicitly because the builder stage has no `.git` to read it from, and Sentry resolves a trace by matching the event's release to the uploaded bundle — a mismatch resolves nothing. `SENTRY_URL` is only needed for a self-hosted Sentry; omit it and the upload goes to `https://sentry.io/`. The maps are deleted from the image once uploaded. Omit all of them and the build simply skips the upload. ## SMTP TLS Certificates [#smtp-tls-certificates] For TLS on ports 465/587, provide certificates via one of these methods: ### Traefik acme.json (Dokploy, Coolify) [#traefik-acmejson-dokploy-coolify] Mount the `acme.json` file and set `SMTP_DOMAIN`: ```yaml environment: SMTP_DOMAIN: "smtp.yourdomain.com" volumes: - /path/to/acme.json:/certs/acme.json:ro ``` Sendly automatically extracts the certificate for `SMTP_DOMAIN` from acme.json. ### PEM Files [#pem-files] Mount certificate files directly: ```yaml volumes: - /path/to/privkey.pem:/certs/privkey.pem:ro - /path/to/fullchain.pem:/certs/fullchain.pem:ro ``` If no certificates are mounted, SMTP runs without TLS. ## Building from Source [#building-from-source] The root `Dockerfile` defaults to `APP=web`, so a bare build produces the web image (see [Building Individual Apps](#building-individual-apps) for the others): ```bash docker build -t sendly-web . ``` --- # Environment Variables (/self-hosting/environment-variables) ## Security & Database [#security--database] | Variable | Required | Description | Example | | -------------- | -------- | ---------------------------------------------------------------------------- | ------------------------------------------------- | | `BETTER_AUTH_SECRET` | Yes | Signing/encryption secret for sessions and for the secret-reveal key (HKDF-derived from it). Must be at least 32 characters. Generate with `openssl rand -base64 32`. | `s3cr3t...` | | `DB_PASSWORD` | Yes | PostgreSQL database password. Used by the Docker Compose setup. | `changeme123` | | `DATABASE_URL` | Yes | Full PostgreSQL connection string. Auto-configured in Docker. | `postgresql://sendly:password@postgres:5432/sendly` | | `REDIS_URL` | Yes | Redis connection string. | `redis://redis:6379` | | `PORT` | No | Port the API server listens on. | `8080` (default) | ## URLs & Domains [#urls--domains] Set your subdomains here. The application automatically derives all internal and client-side URLs from these at container startup — you don't need to set `*_URI` or `NEXT_PUBLIC_*` variables manually. | Variable | Required | Description | Example | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------- | --------------------- | | `API_DOMAIN` | Yes | Subdomain for the API server. | `api.yourdomain.com` | | `DASHBOARD_DOMAIN` | Yes | Subdomain for the dashboard app. | `app.yourdomain.com` | | `LANDING_DOMAIN` | Yes | Subdomain for the landing page. | `www.yourdomain.com` | | `WIKI_DOMAIN` | Yes | Subdomain for the documentation site. | `docs.yourdomain.com` | | `USE_HTTPS` | No | Set to `true` when running behind a TLS-terminating reverse proxy. Used to construct URLs with the correct protocol. | `false` (default) | ## AWS SES [#aws-ses] | Variable | Required | Description | Example | | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- | | `AWS_SES_REGION` | Yes | AWS region where SES is configured. | `us-east-1` | | `AWS_SES_ACCESS_KEY_ID` | Yes | AWS access key ID with SES send permissions. | `AKIA...` | | `AWS_SES_SECRET_ACCESS_KEY` | Yes | AWS secret access key for SES. | `wJalr...` | | `SNS_ALLOWED_TOPIC_ARNS` | Yes | Comma-separated ARN(s) of the SNS topic(s) your SES events and inbound mail are published to. The webhook refuses (403) any message from a topic not listed here, and Sendly will not start without it. In `docker-compose.prod.yml` it is a literal on the `web` service (an ARN is not a secret), so edit that line rather than your env file. | `arn:aws:sns:us-east-1:123456789012:sendly-ses-events` | | `SES_CONFIGURATION_SET` | No | SES configuration set name used for open/click tracking. | `sendly-configuration-set` (default) | | `SES_CONFIGURATION_SET_NO_TRACKING` | No | A second SES configuration set without tracking. When set, projects can toggle email tracking on/off. If omitted, the tracking toggle is hidden. | `sendly-no-tracking-configuration-set` (default) | ## Storage (Minio) [#storage-minio] The bundled Docker setup includes Minio with defaults that work out of the box. Only change these when connecting to an external S3-compatible bucket. | Variable | Required | Description | Default | | ---------------------- | -------- | ------------------------------------------------------------------ | ------------------- | | `MINIO_ROOT_USER` | No | Minio root username (Docker Compose only). | `sendly` | | `MINIO_ROOT_PASSWORD` | No | Minio root password (Docker Compose only). | `sendlyminiopass` | | `MINIO_API_PORT` | No | Port for the Minio API (Docker Compose only). | `29000` | | `MINIO_CONSOLE_PORT` | No | Port for the Minio console UI (Docker Compose only). | `29001` | | `S3_ENDPOINT` | No | S3 or Minio endpoint URL. | `http://minio:9000` | | `S3_ACCESS_KEY_ID` | No | S3 or Minio access key. | — | | `S3_ACCESS_KEY_SECRET` | No | S3 or Minio secret key. | — | | `S3_BUCKET` | No | Bucket name for file uploads. | `uploads` | | `S3_PUBLIC_URL` | No | Publicly accessible base URL for stored files. | — | | `S3_FORCE_PATH_STYLE` | No | Use path-style URLs instead of virtual-hosted. Required for Minio. | `true` | ## SMTP Server [#smtp-server] The optional SMTP relay lets you send emails through Sendly via the SMTP protocol. | Variable | Required | Description | Default | | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------- | | `SMTP_DOMAIN` | No | SMTP relay domain. Required when using Traefik's `acme.json` with multiple certificates so the correct cert can be selected. | `localhost` | | `SMTP_ENABLED` | No | Explicitly enable SMTP features. Automatically enabled when `SMTP_DOMAIN` is set to a non-localhost value in production. | `false` | | `SMTP_PORT_SECURE` | No | SMTPS port (implicit TLS). | `465` | | `SMTP_PORT_SUBMISSION` | No | SMTP submission port (STARTTLS). | `587` | ## OAuth [#oauth] Enables social login. Register an OAuth app with each provider and add the credentials here. | Variable | Required | Description | | --------------------- | -------- | ------------------------------- | | `GITHUB_OAUTH_CLIENT` | No | GitHub OAuth app client ID. | | `GITHUB_OAUTH_SECRET` | No | GitHub OAuth app client secret. | | `GOOGLE_OAUTH_CLIENT` | No | Google OAuth app client ID. | | `GOOGLE_OAUTH_SECRET` | No | Google OAuth app client secret. | ## Stripe [#stripe] All four are required, and there is no "billing disabled" mode. While they were optional the app derived a `STRIPE_ENABLED` flag from their presence, which made the monthly usage cap, the pre-send campaign billing check and usage metering into silent no-ops on any install that had not configured Stripe — enforcement became a function of how completely someone had filled in their environment. A missing value now fails boot instead. There is no flat-monthly price. Checkout sells one metered line item, and `STRIPE_PRICE_PRO_FLAT_MONTHLY` (formerly `STRIPE_PRICE_ONBOARDING`) is a retired name that fails boot if it is still set. | Variable | Required | Description | | -------------------------- | -------- | --------------------------------------------------------------------- | ------------------ | | `STRIPE_SK` | Yes | Stripe secret key. | | `STRIPE_WEBHOOK_SECRET` | Yes | Stripe webhook signing secret for verifying events. | | `STRIPE_PRICE_EMAIL_USAGE` | Yes | Stripe price ID for the metered, graduated pay-per-email usage price. | | `STRIPE_METER_EVENT_NAME` | Yes | Stripe meter event name. | `emails` (default) | ## Platform Emails [#platform-emails] When configured, Sendly will send email notifications to users for critical events (e.g. project disabled, billing limits reached). Without these, only ntfy notifications are sent. | Variable | Required | Description | Example | | ------------------------------ | -------- | ----------------------------------------------------------- | ------------------------ | | `SENDLY_PLATFORM_SEND_API_KEY` | Yes | API key Sendly sends its OWN platform mail with. | `pk_...` | | `SENDLY_FROM_ADDRESS` | Yes | From address used for platform notification emails. | `noreply@yourdomain.com` | ## Notifications (ntfy) [#notifications-ntfy] Sendly bundles a self-hosted [ntfy](https://ntfy.sh) server for internal system notifications. | Variable | Required | Description | Default | | ----------- | -------- | ----------------------------------------------------------------------------------- | --------------------------------- | | `NTFY_PORT` | No | Port for the ntfy web UI (Docker Compose only). | `8080` | | `NTFY_URL` | No | ntfy topic URL. Change this to use an external ntfy.sh server or your own instance. | `http://ntfy/sendly-notifications` | ## Security [#security] | Variable | Required | Description | Default | | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `EMAIL_RATE_LIMIT_PER_SECOND` | No | Override the email sending rate limit, in emails per second. If not set, Sendly automatically fetches the quota from your AWS SES account. When set it is a hard ceiling — it applies whether the SES quota is higher or lower. **Fractional values below 1 are supported** for deliberately slow sending: `0.16` paces roughly one email every 6.25 seconds (~48 per 5 minutes), which is useful while warming up a new SES account or rebuilding sender reputation. Must be greater than 0. | — | ## Phishing Detection [#phishing-detection] Sendly uses AI to detect and block phishing emails before they're sent. This requires an [OpenRouter](https://openrouter.ai) API key — the app fails at startup without one, so that content scanning can never be silently disabled. | Variable | Required | Description | Default | | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | --------------------------- | | `OPENROUTER_API_KEY` | **Yes** | OpenRouter API key. Powers outbound phishing detection and inbound spam classification. | — | | `OPENROUTER_ASSISTANT_MODEL` | No | LLM model for the AI assistant. See [OpenRouter models](https://openrouter.ai/models). | `anthropic/claude-haiku-4.5` | | `OPENROUTER_MODERATION_MODEL` | No | Classification model for phishing/spam scanning. Avoid reasoning models (they can return empty content). | `deepseek/deepseek-v4-flash` | | `PHISHING_SAMPLE_RATE_DEFAULT` | No | Rate (0.0-1.0) for a sender with 10,000-100,000 lifetime sends; the rungs either side scale from it (2.5x below, 0.5x above). `0.1` means 10% of emails are analyzed. | `0.1` (10%) | | `PHISHING_FULL_SCAN_FIRST_SENDS` | No | Every project's first N sends are analyzed in full, whatever its age or plan. `0` turns it off. | `1000` | | `PHISHING_SAMPLE_RATE_FLOOR` | No | The lowest rate any sender is ever analyzed at. Must be at least `0.001`: `0` refuses boot. | `0.02` (2%) | | `PHISHING_CONFIDENCE_THRESHOLD` | No | Minimum confidence percentage (0-100) at which a phishing verdict of any category auto-disables a project; a lower-confidence flag is held for operator review. | `85` | | `PHISHING_CUMULATIVE_THRESHOLD` | No | Number of held emails within the time window at which the operator page escalates to urgent. | `3` | | `PHISHING_CUMULATIVE_WINDOW_MS` | No | Time window in milliseconds for cumulative phishing tracking. | `3600000` (1 hour) | | `PHISHING_BLOCKLISTED_DOMAINS` | No | Comma-separated domains; any email linking to one (or a subdomain) auto-disables the project, whatever the scanner says. | Blank | Paid fallback is optional, server-only, and only takes effect when `OPENROUTER_API_URL` points at a gateway that supports it; leave the three variables blank otherwise. The key is sent only for signed-in users' requests, never for guests or CI/evals. Each model request can go paid once (no paid retries), and an assistant turn is one request per step, so put a spending limit on the key itself: that limit is the only hard cap. | Variable | Required | Description | Default | | --- | --- | --- | --- | | `OPENROUTER_FALLBACK_API_KEY` | No | Your own `sk-or-v1-...` OpenRouter key for the paid retry; blank disables paid fallback. | Blank | | `OPENROUTER_FALLBACK_MODEL` | No | Optional paid model id (`vendor/model`). It must accept every parameter the app sends, e.g. `reasoning` and `response_format`. | Gateway default | | `OPENROUTER_FALLBACK_AFTER_SECONDS` | No | Seconds to wait on the free route before going paid: a plain number above 0 and at most 12. | `8` | | `OPENROUTER_BATCH_API_KEY` | No | A second proxy key for background moderation (send-time phishing scans, inbound spam classification): low priority, its own budget, never paid. Blank uses `OPENROUTER_API_KEY`. | Blank | | `OPENROUTER_MODERATION_FREE_SECOND_MODEL` | No | A free proxy model id the Devino proxy may answer with when the moderation model is slow or throttled. Sent with every phishing scan and spam classification, to the proxy only. Use a different vendor than `OPENROUTER_MODERATION_MODEL`. Empty: not sent. | **How it works:** - Every project's first `PHISHING_FULL_SCAN_FIRST_SENDS` emails are analyzed by the LLM for phishing content. After that a sample is analyzed, with a rate that falls as the project sends more (`PHISHING_SAMPLE_RATE_DEFAULT` is the middle rung) but never below `PHISHING_SAMPLE_RATE_FLOOR`. While a project has an email held for review, was flagged within `PHISHING_CUMULATIVE_WINDOW_MS`, added a sending domain in the last 7 days, or has bounces or complaints in the warning band, every one of its emails is analyzed. - An email flagged below `PHISHING_CONFIDENCE_THRESHOLD` is **held for review**: it is not sent, the project keeps running, and the operator is paged on `NTFY_URL`. It is sent only when an operator passes it (`/api/internal/ops/phishing-holds`, behind `INTERNAL_SERVICE_TOKEN`); a hold never times out into a send. A pass covers the content that was reviewed: the email is sent exactly as it was stored when it was queued, so a snippet or contact field edited afterwards changes nothing that goes out and is not analyzed again. An operator can also reject it, and optionally disable the project. An API send request or a hosted-mailbox message flagged the same way is refused at once and kept for review; a pass lets the same content through when it is sent again. - A project is disabled automatically only when **either**: 1. an email is flagged, in any category, with confidence ≥ `PHISHING_CONFIDENCE_THRESHOLD`, **or** 2. any email links to a domain in `PHISHING_BLOCKLISTED_DOMAINS` (checked on every send, sampled or not). - `PHISHING_CUMULATIVE_THRESHOLD` or more held emails within `PHISHING_CUMULATIVE_WINDOW_MS` escalate the page; they do not disable the project. Emails an operator passed do not count. - Detection history is stored in Redis and shared across all worker instances. --- # AWS SES Setup (/self-hosting/email-setup) ## 1. Create IAM User [#1-create-iam-user] 1. Go to IAM Console → Users → Create user 2. Name: `sendly-ses` 3. Attach a custom policy with required permissions (see below) 4. Create access keys → Save credentials ### Required IAM Policy [#required-iam-policy] ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ses:SetIdentityMailFromDomain", "ses:GetIdentityDkimAttributes", "ses:SendRawEmail", "ses:GetIdentityVerificationAttributes", "ses:VerifyDomainDkim", "ses:ListIdentities", "ses:SetIdentityFeedbackForwardingEnabled" ], "Resource": "*" } ] } ``` ## 2. Create SNS Topic [#2-create-sns-topic] 1. Go to SNS Console → Topics → Create topic 2. Type: Standard 3. Name: `sendly-ses-events` 4. Create topic 5. Create subscription: - Protocol: HTTPS - Endpoint: `https://api.yourdomain.com/webhooks/sns` 6. Set `SNS_ALLOWED_TOPIC_ARNS` to the topic's ARN (in `docker-compose.prod.yml` it is the literal on the `web` service; copy the ARN from the topic's detail page; use a comma-separated list if you have more than one topic, for example one per region). Do this before subscribing: Sendly refuses any message from a topic that is not listed, including the subscription confirmation. 7. Sendly automatically confirms the subscription. If it fails, check your logs for the confirmation URL. ## 3. Create Configuration Sets [#3-create-configuration-sets] ### Tracking Configuration Set [#tracking-configuration-set] 1. SES Console → Configuration sets → Create set 2. Name: `sendly-tracking` 3. Add event destination: - Name: `sns-events` - Event types: **Sends, Deliveries, Opens, Clicks, Bounces, Complaints** - Destination: SNS → Select `sendly-ses-events` topic ### No-Tracking Configuration Set [#no-tracking-configuration-set] 1. Create another set named `sendly-no-tracking` 2. Add event destination with only: **Sends, Deliveries, Bounces, Complaints** ## 4. Configure Environment [#4-configure-environment] ```bash AWS_SES_REGION="us-east-1" AWS_SES_ACCESS_KEY_ID="your-access-key" AWS_SES_SECRET_ACCESS_KEY="your-secret-key" SNS_ALLOWED_TOPIC_ARNS="arn:aws:sns:us-east-1:123456789012:sendly-ses-events" SES_CONFIGURATION_SET="sendly-tracking" SES_CONFIGURATION_SET_NO_TRACKING="sendly-no-tracking" ``` ## 5. Add Your Domain in Sendly [#5-add-your-domain-in-sendly] Once you have configured AWS SES with the above settings, you can add and verify your domain directly through the Sendly dashboard. Sendly will handle the domain verification and DKIM setup with AWS SES automatically and show you the right records to add to your DNS.
    {{@index}}{{name}}{{price}}
    Your order is empty.