Per agenti AI

Server MCP di SendHQ

Give an AI agent full, safe control of one SendHQ workspace: send and receive email, verify domains, publish templates, and investigate deliverability through 142 strictly typed tools. Written for agents first; humans welcome.

142 toolsstdio transport, one command0 key-management tools
Installa e collega (Claude Code)
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

Che cos'è questo server

The SendHQ MCP server lets an AI agent operate one SendHQ workspace through the Model Context Protocol: send email (single, batch, templated, replies, attachments, idempotent retries), read and search sent and received mail (subjects, bodies, and attachment names) and its delivery events, organize mail into labels with auto-filing rules, manage drafts and private attachments, author and publish hosted templates, add and verify domains and their DNS, set up inbound receiving and inbound addresses, inspect deliverability, bounces, complaints, and suppressions, run newsletters (consented contacts with tags and custom fields, segments, lists with signup forms, welcome emails, and newsletter sites, and broadcasts with pre-send checks, test sends, scheduling, and bot-filtered open and click reports), and read account usage, billing state, analytics, and API-key metadata.

È un server stdio locale integrato nel binario della CLI sendhq. Il tuo client MCP avvia sendhq mcp come processo figlio e comunica in JSON-RPC su stdin/stdout. Ogni chiamata a uno strumento diventa una richiesta documentata all'API REST di SendHQ su https://sendhq.cc/api/v1, autenticata con la chiave API del tuo workspace: il server MCP ha quindi esattamente i permessi di quella chiave, non uno di più.

  • 142 tools in 10 groups, generated from one catalog that is also published as tools.json.
  • JSON Schema rigorosi: argomenti sconosciuti, tipi errati e campi obbligatori mancanti vengono rifiutati in locale, prima che qualcosa arrivi a SendHQ.
  • Errori strutturati con un code stabile, lo status HTTP, una explanation, un remedy concreto e l'indicazione se un nuovo tentativo può essere utile.
  • Ogni strumento che invia email reali o distrugge dati lo dichiara nelle prime parole della sua descrizione e riporta le annotazioni di sicurezza MCP.
  • La modalità --read-only nasconde tutti gli strumenti che inviano o modificano dati.
  • Non viene registrato nulla. stdout trasporta solo messaggi di protocollo; la chiave API e il contenuto dei messaggi non finiscono mai in un log.
Non è l'endpoint MCP della documentazione.SendHQ ospita anche un piccolo endpoint MCP di sola lettura per la documentazione su https://sendhq.cc/api/mcp (consultazione di prezzi e documentazione, nessun accesso all'account). Il server descritto in questa pagina è quello completo, con ambito limitato all'account; gira in locale oppure come connettore ospitato descritto più sotto.

Use SendHQ in Claude, ChatGPT and Grok

Nessuna installazione necessaria: SendHQ esegue questo server anche come connettore ospitato su https://mcp.sendhq.cc/mcp, con gli stessi strumenti. Accedi con il tuo account SendHQ invece di incollare una chiave.

Claude

  1. Apri Impostazioni → Connettori e cerca SendHQ nella directory, oppure scegli Aggiungi connettore personalizzato e incolla https://mcp.sendhq.cc/mcp.
  2. Fai clic su Connetti, accedi a SendHQ, controlla l'accesso richiesto e fai clic su Consenti.
  3. Chiedi a Claude di controllare la tua inbox, inviare un'email dal tuo dominio verificato o spiegarti un bounce.

ChatGPT

  1. Open Settings → Security and login and turn on Developer mode.
  2. Go to chatgpt.com/plugins, click Create MCP app, name it SendHQ and enter https://mcp.sendhq.cc/mcp.
  3. Sign in to SendHQ and click Allow, then pick SendHQ from the tools menu in a new chat.

Grok

  1. Go to grok.com/connectors, click New Connector, then Custom.
  2. Enter https://mcp.sendhq.cc/mcp, sign in to SendHQ and click Allow.

Muse by Meta

In Muse, open Connectors and search for SendHQ. Click Connect, sign in to SendHQ and click Allow.

Approvazione e disconnessione

  • The request_feature tool sends a feature request to the SendHQ team with your account details, so we can follow up by email.
  • Gli strumenti che inviano email reali o eliminano dati sono etichettati come tali. Se l'assistente debba chiederti conferma prima si imposta per singolo strumento nell'assistente: in Claude, scegli Richiede approvazione per quegli strumenti in Impostazioni → Connettori → SendHQ.
  • Il connettore riceve una propria chiave API, con il nome dell'assistente (ad esempio “Claude (AI connector)”). Eliminala in Chiavi API per disconnetterlo immediatamente.
  • Non può creare né revocare chiavi API né modificare la fatturazione. Gli allegati vengono inviati e restituiti in base64; non c'è accesso ai file locali.
  • Sending requires an active subscription. There is no free allowance, including mail to the account owner.

Domande: postmaster@sendhq.cc. Privacy: sendhq.cc/privacy.

Installazione

Installa il binario sendhq (Linux, macOS e Windows su x86-64 e arm64). L'installer verifica il checksum della release e, per impostazione predefinita, colloca il binario in ~/.local/bin.

macOS e Linux
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
Windows PowerShell
irm https://downloads.sendhq.cc/install.ps1 | iex
Verifica l'installazione
sendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor

Crea una chiave API nella dashboard su https://sendhq.cc/app#/keys. Il server MCP non può creare chiavi. L'unico comando che avvia il server è:

Avvia il server stdio
SENDHQ_API_KEY=re_your_key sendhq mcp

Di solito non lo esegui mai a mano: è il client MCP ad avviarlo. Se lo lanci in un terminale, resta in attesa di JSON-RPC su stdin.

Configura il tuo client

Claude Code

claude mcp add
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

# read-only variant
claude mcp add sendhq-readonly --env SENDHQ_API_KEY=re_your_key -- sendhq mcp --read-only

Aggiungi --scope user per renderlo disponibile in tutti i progetti, oppure --scope project per scriverlo nel file .mcp.json del progetto. Per un .mcp.json condiviso, fai riferimento alla chiave tramite l'ambiente invece di committarla; Claude Code espande ${VAR} in .mcp.json.

.mcp.json
{
  "mcpServers": {
    "sendhq": {
      "command": "sendhq",
      "args": [
        "mcp"
      ],
      "env": {
        "SENDHQ_API_KEY": "${SENDHQ_API_KEY}"
      }
    }
  }
}

OpenAI Codex

~/.codex/config.toml
[mcp_servers.sendhq]
command = "sendhq"
args = ["mcp"]
env = { SENDHQ_API_KEY = "re_your_key" }

Oppure da riga di comando: codex mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp.

Claude Desktop

Modifica claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) e riavvia l'app. Le app desktop non ereditano il PATH della tua shell, quindi usa il percorso assoluto del binario (which sendhq).

claude_desktop_config.json
{
  "mcpServers": {
    "sendhq": {
      "command": "/Users/you/.local/bin/sendhq",
      "args": [
        "mcp"
      ],
      "env": {
        "SENDHQ_API_KEY": "re_your_key"
      }
    }
  }
}

Qualsiasi altro client MCP

Configura un server stdio con il comando sendhq, gli argomenti ["mcp"] (facoltativamente "--read-only") e le variabili d'ambiente riportate sotto. Il server supporta le versioni del protocollo MCP 2024-11-05, 2025-03-26, 2025-06-18 e 2025-11-25, e implementa initialize, ping, tools/list e tools/call. I risultati degli strumenti contengono sia un blocco di testo JSON sia structuredContent.

Smoke test stdio grezzo (da passare in pipe a sendhq mcp)
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_service_health","arguments":{}}}

Non esiste un trasporto HTTP ospitato per il server con ambito limitato all'account. Un endpoint MCP remoto con permessi di scrittura richiederebbe OAuth per utente, che SendHQ non offre; il binario locale tiene la chiave sulla macchina che già la custodisce.

Ambiente e flag

Variabile o flagObbligatorioSignificato
SENDHQ_API_KEYsìChiave API del workspace (re_…). Serve a tutti gli strumenti tranne get_service_health. Senza di essa il server si avvia comunque, ma ogni chiamata restituisce un auth_error strutturato che spiega come risolvere.
SENDHQ_API_BASE_URLnoURL di base dell'API. Predefinito: https://sendhq.cc/api/v1. Usalo solo per un deployment locale o di staging. SENDHQ_BASE_URL è accettato come alias legacy.
SENDHQ_MCP_READ_ONLYno1, true o yes equivalgono a --read-only.
--read-onlynoEspone solo gli strumenti che non inviano email e non modificano lo stato. Anche gli strumenti nascosti vengono rifiutati se chiamati per nome.
SENDHQ_PROFILE / --profilenoUsa una chiave salvata da sendhq auth login nel keyring del sistema operativo invece di SENDHQ_API_KEY. Se esistono entrambe, prevale la variabile d'ambiente.

La chiave viene inviata solo come intestazione Authorization: Bearer all'URL di base configurato. Non viene mai stampata, registrata nei log, ripetuta negli errori o inclusa nei risultati degli strumenti.

Modello di sicurezza per gli agenti

  • Sends real email. send_email, send_batch, send_template_test, send_broadcast, send_broadcast_test, schedule_broadcast (at the scheduled time), and send_broadcast_to_more deliver mail to real people and consume delivery credits. Their descriptions start with SENDS REAL EMAIL. Call them only when the user explicitly asked for that specific message to be sent, with the recipients, sender, and content confirmed.
  • Destructive. delete_email, delete_draft, delete_attachment, delete_domain, delete_inbox, remove_suppression, the campaign deletes (delete_contact, delete_list, remove_list_contact, delete_broadcast, cancel_broadcast, delete_segment, delete_contact_field), and bulk_update_contacts are marked destructiveHint: true and their descriptions start with DESTRUCTIVE. Confirm with the user first. remove_suppression weakens a safety block and is appropriate only when a human confirms the address works again.
  • Modificano lo stato. Creare o aggiornare bozze, template, domini e inbox, pubblicare template e avviare la verifica modificano il workspace, ma non inviano posta.
  • Sola lettura. Tutto il resto è readOnlyHint: true e si può chiamare liberamente.
  • Questo server non modifica mai il DNS. add_domain restituisce i record che una persona deve pubblicare; get_domain_connect_link restituisce un URL di consenso che una persona deve aprire e approvare presso il proprio provider DNS.
  • Questo server non modifica mai la fatturazione. get_account legge solo piano, utilizzo e stato dell'abbonamento.
  • Sending requires an active subscription. There is no free allowance. Every send, including a test and a send to the account owner's own address, returns subscription_required (402) until a plan is active. Lapsed, cancelled, and past-due subscriptions are refused the same way. The owner chooses a plan in the dashboard (Profile & Billing) or at https://sendhq.cc/pricing. Unpaid workspaces can still verify domains, create keys, and read the workspace.
  • Accepted is not delivered. A successful send returns an ID; delivery, bounce, and complaint evidence arrives later in list_email_events. Never claim inbox placement or that a person read a message. Broadcast opens are estimates: privacy proxies and security scanners load images on their own, and requests that look automated are counted apart (machine in get_broadcast_report).
  • Non passare a un altro indirizzo From per aggirare una pausa 423, e non aggiungere mai di nuovo destinatari che si sono disiscritti o hanno segnalato spam.

Le chiavi API sono escluse

Per scelta progettuale non esistono strumenti che creano, modificano, ruotano, revocano o eliminano chiavi API. Un agente non deve generare né distruggere credenziali. list_api_keys restituisce solo nomi, prefissi non segreti e data dell'ultimo utilizzo. La gestione delle chiavi resta nella dashboard, in mano a una persona che ha effettuato l'accesso.

Flussi di lavoro

1. Primo invio

  1. get_service_health conferma che l'API è raggiungibile (funziona senza chiave).
  2. get_account shows the plan (access.tier) and remaining quota. If there is no active plan, do not send: the call returns subscription_required.
  3. list_sending_identities elenca gli indirizzi From che puoi usare. Se è vuoto, completa prima il flusso del dominio.
  4. Conferma con l'utente mittente, destinatario, oggetto e corpo, poi chiama send_email con una idempotency_key.
  5. list_email_events con l'id restituito mostra delivery, bounce, complaint o reject non appena il provider lo segnala (di solito da pochi secondi a qualche minuto).
Primo invio
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "SendHQ is connected",
    "text": "It works.",
    "idempotency_key": "first-send-2026-09-26"
  }
}

2. Verifica del dominio dall'inizio alla fine

  1. add_domain with name: "example.com". The result includes the DNS records (DKIM CNAMEs, domain verification, SPF, recommended DMARC).
  2. get_dns_provider con il domain_id rileva il provider DNS autoritativo e restituisce l'host relativo esatto da inserire per ogni record presso quel provider.
  3. If providers.domainConnect.available is true, get_domain_connect_link returns a consent URL. Give it to the human; nothing changes until they approve at the provider. Otherwise, give the human the records to publish. Never publish a second SPF record: merge SendHQ's SPF include (include:amazonses.com) into the existing v=spf1 value.
  4. verify_domain rechecks DNS and DKIM verification. Status moves through pending, checking, and propagating to verified. Poll verify_domain or get_domain every 30–60 seconds; DNS can take minutes to hours.
  5. Quando status è verified, gli indirizzi del dominio compaiono in list_sending_identities.

3. Bounce, segnalazioni di spam e soppressioni

  1. list_blocked_recipients restituisce ogni indirizzo bloccato con il relativo motivo (bounce, complaint, unsubscribe) e un conteggio riassuntivo.
  2. list_suppressions restituisce le soppressioni per hard bounce e per segnalazione di spam; deliverability_stats fornisce i tassi di consegna, bounce e segnalazioni di spam degli ultimi 30 giorni; list_sender_reputation mostra quali indirizzi From sono rallentati o in pausa.
  3. Un invio che contiene un destinatario soppresso fallisce con 422 recipient_suppressed. Rimuovi quel destinatario e invia di nuovo.
  4. Chiama remove_suppression solo quando una persona conferma che una casella in bounce ora funziona. Le soppressioni per segnalazione di spam sono permanenti (409 complaint_suppression_locked).

4. Ricevere email in entrata

  1. Il dominio (spesso un sottodominio come inbound.example.com) deve essere verificato.
  2. setup_inbound predispone la ricezione e restituisce un record MX, che una persona pubblica.
  3. verify_inbound finché status non è ready.
  4. create_inbox con domain_id e local_part (ad esempio support) crea support@inbound.example.com.
  5. Interroga periodicamente list_emails con direction: "in" e unread: true (facoltativamente inbox_id). Leggi un messaggio con get_email, la sua conversazione con get_thread, gli allegati con download_attachment, e segnalo come gestito con mark_email (read: true).
  6. Rispondi nel thread con send_email e reply_to_email_id; SendHQ imposta In-Reply-To, References e il thread.

5. Webhook e notifiche degli eventi

Webhooks push signed events to an endpoint a human configures in the dashboard or with the REST API (see /docs/webhooks): email events (email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.failed, email.received), contact.unsubscribed when a recipient unsubscribes from a marketing or automation email, and, for automations, automation.entered, automation.converted, and automation.exited. There is no webhook tool, because endpoint responses carry signing secrets. An agent without a webhook polls instead: list_email_events for one message's outcome, list_emails with status (for example bounced) or after for recent changes, list_emails with direction: "in" and unread: true for new inbound mail, and list_blocked_recipients for new suppressions. Poll no more than about once a minute per question.

6. Diagnosticare un errore di consegna

  1. Trova il messaggio: list_emails con direction: "out" e to o query, oppure get_email se hai l'ID. status: failed significa che SendHQ o il provider lo ha rifiutato all'invio; l'errore dell'email spiega il motivo.
  2. list_email_events: bounce (permanente o transitorio, con la diagnostica del provider), complaint, reject o delivery. Se non ci sono ancora eventi, il provider non ha ancora segnalato nulla: attendi e ricontrolla.
  3. If the send call itself failed, read the error code: subscription_required → the owner activates a plan; sender_domain_unverified → finish domain verification; recipient_suppressed → the address hard-bounced or complained before; sender_paused → inspect list_sender_reputation; account_paused → the workspace is paused for review, read the rates; daily_limit_reached → wait until midnight UTC; quota_exhausted → get_account usage.
  4. get_domain controlla che DKIM, SPF e DMARC siano ancora pubblicati; deliverability_stats mostra se il problema riguarda un solo messaggio o è una tendenza.
  5. Riporta ciò che mostrano le prove. Un evento delivery significa che il server del destinatario ha accettato il messaggio, non che è arrivato in inbox o è stato letto.

7. Gestire un bucket di lavoro (etichette)

  1. create_label con name (ad esempio Agent/Orders) e skip_inbox: true. Così l'etichetta diventa un bucket: la posta ricevuta che la ottiene viene archiviata, quindi compare solo nell'etichetta e mai nella Inbox della persona.
  2. Invia la posta di lavoro con send_email (o send_batch) e labels: ["Agent/Orders"]. Le risposte a quella conversazione ereditano automaticamente l'etichetta e saltano la Inbox.
  3. Per la posta che nasce fuori dalle tue conversazioni, aggiungi una regola di archiviazione: create_label_rule con inbox_id (un indirizzo dedicato come orders@…), from, to o subject. Passa apply_to_existing: true per archiviare anche la posta già ricevuta.
  4. Lavora sul bucket: list_emails con label: "Agent/Orders", direction: "in" e unread: true; leggi con get_email o get_thread, rispondi con send_email e reply_to_email_id, e chiama mark_email read: true una volta gestito.
  5. Sposta un messaggio fuori posto dentro o fuori con label_email (add / remove). Aggiungere l'etichetta di un bucket a un messaggio ricevuto lo archivia anche.
  6. Facoltativamente, set_inbox_forwarding invia a un'altra casella una copia di tutto ciò che riceve un indirizzo (la destinazione conferma prima via email).
Inviare in un bucket
{
  "name": "send_email",
  "arguments": {
    "from": "Orders <orders@example.com>",
    "to": [
      "customer@example.net"
    ],
    "subject": "Order 1042: confirm delivery window",
    "text": "Reply with a time that works.",
    "labels": [
      "Agent/Orders"
    ],
    "idempotency_key": "order-1042-window"
  }
}

8. Allegati e template

Con un piano a pagamento, allega fino a 10 file con attachments di send_email (ognuno richiede content_base64 o un file_path locale; filename ha come valore predefinito il nome base del file). Per i template ospitati: create_template → update_template_draft → render_template per l'anteprima con dati di esempio → send_template_test (invia un test reale) → publish_template, quindi invia con send_email o send_batch usando template: {key, data} ed esattamente un destinatario to.

9. Send a newsletter

  1. Audience: list_lists (or create_list with a signup form), and optionally preview_segment then create_segment to narrow it, for example to contacts tagged VIP who opened in the last 90 days. Add only people who asked for your email: every subscribed contact needs a consent_basis.
  2. get_newsletter_settings: if postalAddress is empty, ask the user for one and set it with update_newsletter_settings (marketing email needs it).
  3. create_broadcast with list_id, a verified from, subject, preview_text, content (markdown is simplest), and optionally audience (segment_id, limit, order: engaged).
  4. check_broadcast: fix every block item and tell the user about warn items. Then send_broadcast_test to the user's own address so they can look at it.
  5. Only when the user says to send: send_broadcast now (with an idempotency_key), or schedule_broadcast with scheduled_at (unschedule_broadcast to change it).
  6. Follow up with get_broadcast (delivery totals), get_broadcast_report (opens, clicks, links, inbox providers, against your average), and list_broadcast_recipients with activity. Report opens as estimates. With a limited audience, send_broadcast_to_more sends to the next people.
Draft a broadcast
{
  "name": "create_broadcast",
  "arguments": {
    "list_id": "lst_…",
    "from": "Acme <news@example.com>",
    "subject": "What shipped in October",
    "preview_text": "Three new features",
    "markdown": "Hi {{first_name | there}},\n\nHere is what shipped this month.",
    "audience": {
      "segment_id": "seg_…"
    }
  }
}

10. Run an automation

An automation is a timed sequence of emails that starts when a contact does something and stops when they convert. Automations are being enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled from every tool below.

  1. create_automation with a key, the entry event, exit_rules (the goal_event that counts as converting, or no_goal: true), a verified from_address, and steps, each due offset_seconds after the person entered. It starts as a draft and sends nothing. Every automation carries domain, the domain of its from_address; in a workspace that sends from several domains, list_automations and get_automations_overview take domain to show the automations of one of them.
  2. To let the user read it first: send_automation_test_email sends one email, and send_automation_test every email in order, to the account's own address only (never to a contact), with stand-in values for the merge tags. A test enrols nobody, is in no report, and works while the automation is still a draft. Both send real email, so only when the user asks. send_automation_test_email with dry_run: true returns the rendered email without sending anything.
  3. get_sending_limits shows how much automation email one person may get across every automation, and during which hours. Change them with update_sending_limits only when the user asks.
  4. To start from a ready-made email instead of writing one: list_automation_templates is the template library (welcome, onboarding tips, a nudge to finish setup, trial ending and trial ended, abandoned checkout, failed payment or dunning, receipt, upgrade at a usage limit, feature announcement, review request, feedback score, cancellation survey, and winback for retention), get_automation_template shows one with the email as this workspace would send it, and use_automation_template makes the draft automation with the emails, the suggested entry event and the suggested goal. Some templates come as a set that makes one automation: three onboarding tips, trial ending then trial ended, payment failed then a last notice. set_automation_step with template loads one template into an email of an automation that already exists.
  5. An email can also be built in the dashboard's drag-and-drop builder. get_automation shows such an email with editor design: its content is the builder's project, which only the builder writes, and its html is what is sent. Leave the project alone. To change the wording of a designed email, ask the user to open it in the dashboard; to replace it, send your own html with editor html.
  6. A template is finished except for what only the user knows, written as placeholders in square brackets: [First step], or [Link to plans] as a link's address. to_fill on the automation lists each one by email, and each workspace name the emails print that is blank. Ask the user for the real words and links, write them in with set_automation_step, and set product_name and sender_name with update_sending_limits. Never invent them. set_automation_status refuses to turn the automation on while anything is left (422 automation_not_ready, with a problems list that names each email and detail); test emails are allowed, so the user can read it first.
  7. Only when the user says to start: set_automation_status with status: "on".
  8. Record what people do with track_event (a new contact needs contact.consent_basis). The entry event starts the sequence, the goal event ends it as converted, and a dedupe_key makes a retry harmless. enroll_contact and exit_contact add or remove one person by hand.
  9. preview_automation shows, for everyone in the automation now, which email would go out if they were evaluated at this moment, or why not: nothing due until a time, held by a limit or the sending hours until a time, waiting behind a higher-priority automation, or skipped. It sends nothing and changes nothing.
  10. list_automations gives each automation's 30-day totals. An email that a limit holds back is not dropped: it goes out when the limit allows. When several emails of one automation are due at once, only the latest is sent.
  11. Results: get_automations_overview (every automation) and get_automation_report (one automation, with a row per email) give totals and a number for each day of a date range: people who entered, emails sent, delivered, opened, clicked, and converted. list_automation_people lists who did what (did: entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, or waiting), and get_automation_person gives one contact's history with every open and click. Automation emails are tracked like broadcasts: report opens and clicks as estimates, and note that automated requests are labelled machine and never counted.
Start from a template
{
  "name": "use_automation_template",
  "arguments": {
    "template_id": "payment-failed-notices",
    "from_name": "Dana from Acme",
    "from_address": "dana@example.com"
  }
}
Dry run
{
  "name": "preview_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Who clicked the first email
{
  "name": "list_automation_people",
  "arguments": {
    "automation_key": "checkout-recovery",
    "did": "clicked",
    "step": 1
  }
}

11. See what came in, and connect another system

Events reach SendHQ three ways: track_event from the workspace's own code, a connection (a secret address a payment provider or another system posts its webhooks to), and a spreadsheet uploaded in the dashboard. See /docs/events.

  1. list_events is the feed of everything recorded, newest first: who, what they did (also as plain words), when, where it came from, and which automations it started, ended, or converted. Filter by contact, by name, or by date. list_event_names lists the kinds of event seen in the last 30 days.
  2. list_connections shows each connection with its last delivery in plain words, and get_connection its last 50 deliveries: "Recorded 2 events", "Skipped: no email address", "Refused: bad signature". Start there when something a provider sent did not show up.
  3. Only when the user asks to connect a system: create_connection with kind stripe or dodo (mapped for you) or generic with a mapping. It returns the secret address once; give it to the user to paste into that system. From then on what arrives is recorded without anyone looking, and can start automations that send email.
  4. update_connection with enabled: false pauses a connection (its address answers 404); delete_connection removes it. The provider's signing secret and a replacement address are set by a person in the dashboard.
What one person did
{
  "name": "list_events",
  "arguments": {
    "contact": "ada@example.net"
  }
}

12. Check an email's content before it is sent

score_email reads a subject, the HTML and the plain text as they were written and returns a score from 0 to 100 with what to change, most points first. A plain email with no links and no images scores 100; a designed layout, links to another site than the sender's, link shorteners, images with few words, hidden text, capitals and very long HTML each take points off. Pass from so links can be compared with the sender's own domain. Nothing is stored or sent, and the footer and tracking SendHQ adds are not scored. The dashboard's email editor shows the same number for the same content. It looks at content only, so use it as a checklist: sender reputation, authentication and how recipients react decide more of where mail lands.

Score a draft
{
  "name": "score_email",
  "arguments": {
    "from": "hello@example.com",
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
  }
}

Risultati, paginazione ed errori

Una chiamata riuscita restituisce l'oggetto JSON dell'API come structuredContent e come blocco di testo JSON. Ogni strumento list_* accetta limit (1–200, predefinito 50) e offset, e aggiunge un oggetto pagination. Continua a chiamarlo con offset: pagination.next_offset finché has_more è true.

Risultato paginato
{
  "data": [
    "…"
  ],
  "count": 50,
  "pagination": {
    "offset": 0,
    "limit": 50,
    "returned": 50,
    "total": 180,
    "has_more": true,
    "next_offset": 50
  }
}

Una chiamata non riuscita restituisce isError: true con un errore strutturato. Segui remedy invece di ritentare alla cieca; ritenta solo quando retryable è true.

Errore strutturato dello strumento
{
  "error": {
    "code": "subscription_required",
    "status": 402,
    "message": "Sending requires an active SendHQ subscription. Choose a plan to start sending.",
    "retryable": false,
    "explanation": "This workspace has no active paid subscription. SendHQ does not send any email, including to the account owner, until a plan is active.",
    "remedy": "Ask the account owner to choose a plan at https://sendhq.cc/pricing or in the dashboard (Profile & Billing). Do not retry until the subscription is active."
  }
}

Campi di errore facoltativi: request_id (da citare al supporto), retry_after_seconds, problems (elenco delle violazioni di schema per invalid_arguments) e idempotent_replayed (vedi Idempotenza).

Idempotenza

send_email e send_batch accettano idempotency_key (massimo 200 caratteri), inviata come intestazione Idempotency-Key. Genera una chiave stabile per ogni messaggio logico, ad esempio invoice-4812-receipt.

  • Un nuovo tentativo deve riutilizzare la stessa chiave E un corpo della richiesta identico. La stessa chiave con una qualsiasi modifica (destinatario, oggetto, corpo, intestazione, dati del template, perfino i valori degli argomenti) restituisce 409 idempotency_conflict.
  • Stessa chiave, stesso corpo, originale completato: SendHQ restituisce il risultato memorizzato senza inviare di nuovo. È così che ritenti in sicurezza dopo un timeout o un network_error.
  • Stessa chiave mentre l'originale è ancora in esecuzione: 409 idempotency_in_progress, ritentabile dopo una breve attesa.
  • Un nuovo messaggio logico richiede una nuova chiave.
  • Anche gli errori memorizzati vengono riprodotti. Se il primo tentativo è fallito, ritentare con la stessa chiave restituisce lo stesso errore con idempotent_replayed: true e retryable: false. Controlla list_emails (direction: out) per confermare che non sia partito nulla, correggi la causa e poi invia con una chiave nuova.
  • Il server non ritenta mai una POST di sua iniziativa. Solo le chiamate GET di sola lettura vengono ritentate automaticamente (fino a 3 tentativi in caso di errori di rete, 429 e 5xx).
  • send_email con attachments inline non accetta una idempotency_key, perché esegue più richieste. Per inviare allegati in modo sicuro rispetto ai nuovi tentativi: create_draft → upload_attachment → send_email con draft_id e idempotency_key.
Invio sicuro da ritentare (ripetilo identico in caso di timeout)
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <billing@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Receipt #4812",
    "text": "Thanks for your payment.",
    "idempotency_key": "receipt-4812"
  }
}

Limiti di frequenza e quote

SendHQ non pubblica un limite fisso di richieste al secondo (rate limit) per l'API. I limiti che un agente incontra davvero sono limiti di utilizzo, restituiti come 429:

  • Consegne mensili per destinatario per piano. Ogni indirizzo To, Cc e Bcc conta come una consegna. Confronta get_account → usage.recipientDeliveries con usage.emailQuotaMonth.
  • Destinatari giornalieri per indirizzo From esatto, stabiliti dallo stato di reputazione di quel mittente (list_sender_reputation → dailyLimit, 2.000 per impostazione predefinita sui piani a pagamento).
  • Subscription: sending is refused with subscription_required until a paid plan is active. There is no free or trial allowance.
  • Workspace daily ladder on paid plans: 1,000 recipients on day one, then 2,000, 3,000, 5,000, 8,000, 12,000, 18,000, 25,000, 35,000, 45,000, and 50,000. A step is gained after a UTC day that used at least half the cap with healthy 7-day feedback. A high rate demotes once per incident, not every day the rate stays high. See get_account → sendingLimit. Over the cap: daily_limit_reached, not queued, retry after resets_at (midnight UTC), not on a short backoff.
  • Hourly pace: about one tenth of the day's cap each UTC hour (100 on day one). hourly_limit_reached waits until the next UTC hour.
  • New domains: a sending domain less than 30 days old may send at most 500 Gmail recipients a day (gmail_recipient_limit), on any ladder rung. gmail_rate_limited means Gmail returned 4.7.28; wait until resets_at and keep sending to other providers.
  • Allegati: al massimo 10 file e 10 MB per messaggio; 10 GB al mese di trasferimento di allegati ponderato per destinatario sui piani a pagamento.
  • Per richiesta: To + Cc + Bcc fino a 100 indirizzi; send_batch fino a 100 messaggi.
  • Circuit breaker della reputazione: in una finestra mobile di 7 giorni, bounce o segnalazioni di spam sopra soglia rallentano o mettono in pausa un indirizzo From (423 sender_paused). Si ripristina automaticamente quando i tassi scendono.

quota_exhausted non è ritentabile finché il periodo non si azzera o il piano non cambia. rate_limited è ritentabile dopo retry_after_seconds; per gli invii, ritenta con la stessa idempotency_key e un corpo identico.

Catalogo degli errori

code è stabile: basa la logica su di esso, non su message.

codeHTTPRitentare?Significato e cosa fare
invalid_arguments—noGli argomenti non hanno superato in locale il JSON Schema dello strumento; nulla è arrivato a SendHQ. Correggi i campi elencati in problems.
auth_error401noChiave API mancante, revocata o errata. Imposta SENDHQ_API_KEY per il processo del server; le chiavi le crea una persona nella dashboard.
subscription_required402noNo active subscription. Nothing is sent, including to the account owner. The owner chooses a plan. Do not retry until then.
payment_required402noLa funzionalità richiede un piano a pagamento (ad esempio gli allegati). Invia senza, oppure passa a un piano superiore.
sender_domain_not_owned403noIl dominio mittente non appartiene a questo workspace. Usa list_sending_identities o add_domain.
sender_domain_unverified403noIl dominio mittente non è ancora verificato. get_domain, pubblica i record mancanti, verify_domain.
domain_limit_reached403noRaggiunto il limite di domini del piano. Rimuovi un dominio inutilizzato (con approvazione) o passa a un piano superiore.
marketing_not_enabled403noLa classe marketing non è abilitata per questo dominio o piano. Usa transactional solo se il messaggio lo è davvero.
forbidden403noLa policy non consente l'operazione. Modifica la richiesta.
not_found404noL'ID non appartiene a questo workspace. Elenca la risorsa per trovare l'ID corretto; ripristina prima i template archiviati.
idempotency_conflict409noChiave riutilizzata con un corpo diverso. Reinvia l'originale esatto, oppure usa una nuova chiave per un nuovo messaggio.
idempotency_in_progress409sìLa richiesta originale è ancora in esecuzione. Attendi, poi ritenta con la stessa chiave e lo stesso corpo.
revision_conflict409noLa bozza del template è cambiata da quando l'hai letta. get_template, unisci le modifiche, salva di nuovo.
complaint_suppression_locked409noIl destinatario ha segnalato spam. Non inviargli mai più email.
inbound_not_ready409noLa ricezione in entrata non è pronta. setup_inbound, pubblica l'MX, verify_inbound.
conflict409noLa risorsa esiste già o è nello stato sbagliato. Leggila e adegua la richiesta.
attachments_too_large413noPiù di 10 file o 10 MB. Rimuovi o riduci gli allegati.
recipient_suppressed422noUn destinatario ha già generato un hard bounce o una segnalazione di spam. Rimuovilo; vedi list_blocked_recipients.
recipient_unsubscribed422noUn destinatario si è disiscritto dalla posta di marketing. Rimuovilo in modo permanente.
validation_failed422noContenuto rifiutato, ad esempio dati del template che violano il contratto delle variabili. Correggi l'input.
sender_paused423noQuesto indirizzo From è in pausa per il circuit breaker di bounce/segnalazioni di spam a 7 giorni. Fermati, correggi la lista, attendi il ripristino automatico.
account_paused423noWorkspace paused for a deliverability review. The body has the measured rate and the limit when the pause was for bounces or complaints. Do not send until it is restored.
quota_exhausted429noMonthly allowance, per-sender daily limit, or attachment transfer. Not the workspace daily ladder. Check get_account; wait for that limit to reset or upgrade.
daily_limit_reached429after resetWorkspace daily ladder. Not a short backoff. Wait until resets_at (midnight UTC). The message was not queued.
hourly_limit_reached429after resetHourly pace (about a tenth of the day's cap). Wait until the next UTC hour. Not a short backoff.
gmail_recipient_limit429after reset500 Gmail recipients a day for a sending domain under 30 days old, on any ladder rung. Wait until midnight UTC. Not queued.
gmail_rate_limited429after resetGmail returned 4.7.28 for this domain. Wait until resets_at. Other providers keep sending.
rate_limited429sìSlow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap.
server_error5xxsìErrore temporaneo di SendHQ o del provider. Applica un backoff e ritenta; per gli invii usa la stessa chiave e lo stesso corpo. Se idempotent_replayed è true, usa una nuova chiave dopo aver confermato che non è stato inviato nulla.
network_error—sìRichiesta o risposta persa. Ritenta; per gli invii la stessa idempotency_key lo rende sicuro.
invalid_request400noRichiesta malformata. Leggi message e correggila.
tool_error—noErrore locale all'interno del server MCP (ad esempio un file_path illeggibile). Leggi message.

Riferimento degli strumenti

Ogni strumento con la sua classe di sicurezza, l'endpoint REST che chiama, i parametri, la struttura della risposta e un oggetto params di esempio per tools/call. I parametri sono esatti: il server rifiuta tutto ciò che non è elencato.

Emails and threads: send_email, send_batch, list_emails, get_email, mark_email, delete_email, list_email_events, get_thread, email_delivery, thread_delivery
Labels and auto-filing rules: list_labels, get_label, create_label, update_label, delete_label, create_label_rule, delete_label_rule, label_email
Drafts, attachments, and sender identities: list_sending_identities, create_draft, list_drafts, get_draft, update_draft, delete_draft, upload_attachment, download_attachment, delete_attachment
Hosted templates: list_templates, create_template, get_template, update_template_draft, create_template_draft, render_template, send_template_test, publish_template, archive_template, restore_template
Domains and DNS: list_domains, get_domain, add_domain, verify_domain, delete_domain, get_dns_provider, get_domain_connect_link
Inbound email: setup_inbound, verify_inbound, list_inboxes, get_inbox, create_inbox, update_inbox, set_inbox_forwarding, delete_inbox
Deliverability, bounces, and suppressions: deliverability_stats, deliverability_account, deliverability_domains, deliverability_senders, score_email, list_sender_reputation, list_suppressions, remove_suppression, list_blocked_recipients
Campaigns: list_contacts, create_contact, upsert_contact, get_contact, update_contact, delete_contact, import_contacts, list_contact_imports, bulk_update_contacts, list_tags, list_contact_fields, set_contact_field, delete_contact_field, list_segments, get_segment, preview_segment, create_segment, update_segment, delete_segment, list_lists, create_list, get_list, update_list, delete_list, add_list_contacts, remove_list_contact, list_broadcasts, create_broadcast, get_broadcast, update_broadcast, delete_broadcast, send_broadcast, cancel_broadcast, list_broadcast_recipients, check_broadcast, send_broadcast_test, schedule_broadcast, unschedule_broadcast, duplicate_broadcast, send_broadcast_to_more, get_broadcast_report, get_newsletter_settings, update_newsletter_settings, get_campaign_overview, list_uploaded_images
Automations, events, and sending limits: track_event, list_automations, get_automation, create_automation, update_automation, delete_automation, set_automation_step, delete_automation_step, set_automation_step_variant, set_automation_status, send_automation_test_email, send_automation_test, enroll_contact, exit_contact, preview_automation, get_automations_overview, get_automation_report, list_automation_people, get_automation_person, get_sending_limits, update_sending_limits, list_automation_templates, get_automation_template, use_automation_template, list_events, list_event_names, list_connections, get_connection, create_connection, update_connection, delete_connection
Account, usage, analytics, and keys: get_account, get_account_diagnostics, get_analytics, list_api_keys, get_service_health

Email e thread

Invia email realisend_email
POST /emails

Invia un'email

SENDS REAL EMAIL. Send one message from a verified domain: raw html/text, a published hosted template, a reply in an existing thread, or a message with attachments. Pass idempotency_key so a retry cannot send twice; a retry must reuse the same key AND an identical request, otherwise SendHQ returns 409. attachments is a convenience that creates a draft, uploads each file, and sends with that draft; it cannot be combined with idempotency_key or draft_id (use create_draft + upload_attachment + send_email with draft_id for retry-safe attachment sends). Unpaid workspaces (integration trial) can deliver only to the account email or a mailbox-simulator test address, and cannot send attachments.

Fornisci almeno uno tra: html, text, template.

ParametroTipoObbligatorioDescrizione
fromstringsìMittente, ad es. Acme <hello@example.com>. Il dominio deve essere verificato in questo workspace (vedi list_sending_identities). (max 998 caratteri)
tostring[]sìDestinatari. Ogni voce è un indirizzo, facoltativamente con un nome visualizzato. To+cc+bcc possono essere al massimo 100 in totale; ogni destinazione consuma un credito di consegna. (1–100 elementi)
ccstring[]noDestinatari in copia. (0–100 elementi)
bccstring[]noDestinatari in copia nascosta. (0–100 elementi)
subjectstringnoOggetto. Omettilo quando invii un template. (max 998 caratteri)
textstringnoCorpo in testo semplice. Fornisci text, html o template.
htmlstringnoCorpo HTML. SendHQ lo sanifica e ne ricava il testo quando text è omesso.
reply_tostringnoIndirizzo Reply-To.
headersobjectnoIntestazioni personalizzate sicure aggiuntive (valori stringa), ad es. {"X-Entity-Ref-ID": "123"}. Le intestazioni di instradamento come From/To/Message-ID sono gestite da SendHQ.
message_classstringnotransactional (predefinito) o marketing. Marketing richiede un piano o un dominio abilitato al marketing e aggiunge la gestione delle disiscrizioni. (uno tra transactional, marketing)
reply_to_email_idstringnoRispondi all'interno di una conversazione esistente: l'ID em_… del messaggio a cui rispondi. SendHQ imposta In-Reply-To/References e il thread.
thread_idstringnoID esplicito del thread in cui archiviare il messaggio.
draft_idstringnoInvia con questo messaggio gli allegati di una bozza salvata (dr_…). La bozza viene eliminata dopo un invio riuscito.
templateobjectnoInvia un template ospitato pubblicato invece di html/testo diretto. Richiede esattamente un destinatario to e nessun cc/bcc; l'oggetto lo fornisce il template. Fornisci almeno uno tra: id, key.
template.idstringnoID del template (tmpl_…). Fornisci id o key.
template.keystringnoChiave del template, ad esempio account-welcome. Fornisci id o key.
template.version_idstringnoID facoltativo della release pubblicata (tmplv_…). Per impostazione predefinita usa la release pubblicata corrente.
template.dataobjectnoValori per le variabili tipizzate del template.
labelsstring[]noNomi di etichetta o ID lbl_… in cui archiviare questo messaggio. I nomi sconosciuti vengono creati. Le risposte nella conversazione ereditano le etichette, e l'etichetta di un bucket (skip_inbox) tiene quelle risposte fuori dalla Inbox. Max 10. (0–10 elementi)
idempotency_keystringnoIntestazione Idempotency-Key (max 200 caratteri). Riutilizzala solo per ritentare esattamente questa richiesta. (max 200 caratteri)
attachmentsobject[]noFile da allegare (max 10 file, 10 MB in totale). Ognuno richiede content_base64 (più filename) o un file_path locale. (0–10 elementi) Fornisci almeno uno tra: content_base64, file_path.
attachments[].filenamestringnoNome del file mostrato al destinatario. Obbligatorio con content_base64; per impostazione predefinita è il nome base di file_path. (max 255 caratteri)
attachments[].content_typestringnoTipo MIME, ad es. application/pdf. Predefinito: application/octet-stream.
attachments[].content_base64stringnoContenuto del file in base64 standard.
attachments[].file_pathstringnoPercorso assoluto di un file locale leggibile dal processo del server MCP.
Restituisce{id: em_…, providerMessageId, threadId, templateId, templateVersionId, isTest}. Accettato non significa consegnato: verifica poi con list_email_events.
Esempio di params per tools/call
{
  "name": "send_email",
  "arguments": {
    "from": "Acme <hello@example.com>",
    "to": [
      "owner@example.com"
    ],
    "subject": "Your export is ready",
    "text": "Download it from your dashboard.",
    "idempotency_key": "export-ready-42"
  }
}
Invia email realisend_batch
POST /emails/batch

Invia un batch di email personalizzate

SENDS REAL EMAIL. Invia da 1 a 100 messaggi indipendenti in una sola richiesta (usalo per personalizzare il template per ogni destinatario). Ogni elemento ha la stessa struttura di send_email (senza attachments/idempotency_key). Gli elementi riescono o falliscono singolarmente: HTTP 207 indica un successo parziale; controlla ogni data[i].ok e data[i].error. Una sola idempotency_key copre l'intero corpo del batch.

ParametroTipoObbligatorioDescrizione
emailsobject[]sìMessaggi da inviare. (1–100 elementi) Fornisci almeno uno tra: html, text, template.
idempotency_keystringnoIdempotency-Key per l'intero batch (max 200 caratteri). (max 200 caratteri)
Restituisce{data: [{index, ok, id?, error?: {message, status}}], count, successful, failed}.
Esempio di params per tools/call
{
  "name": "send_batch",
  "arguments": {
    "emails": [
      {
        "from": "Acme <hello@example.com>",
        "to": [
          "owner@example.com"
        ],
        "template": {
          "key": "account-welcome",
          "data": {
            "first_name": "Asha"
          }
        }
      }
    ],
    "idempotency_key": "welcome-batch-2026-09-26"
  }
}
Sola letturalist_emails
GET /emails

Elenca e cerca le email

Elenca le email inviate (direction: out) e ricevute (direction: in), dalle più recenti, con filtri. La posta ricevuta è classificata: leggi la inbox della persona con direction: in, archived: false, category: primary; fai triage con important: true; lo spam è nascosto a meno di category: spam o include_spam: true. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
directionstringnoin per la posta ricevuta, out per quella inviata. (uno tra in, out)
statusstringnoFiltro di stato, ad es. queued, sent, delivered, bounced, complained, failed.
domainstringnoSolo i messaggi di questo dominio, o di un elenco di domini separati da virgole (corrispondenza con uno qualsiasi).
inbox_idstringnoSolo i messaggi ricevuti da questa inbox (inb_…).
labelstringnoSolo i messaggi con questa etichetta: un ID lbl_… o il nome esatto, oppure un elenco separato da virgole (corrispondenza con uno qualsiasi). Usa list_labels per vedere le cartelle.
archivedbooleannofalse = la vista Inbox (posta ricevuta non archiviata), true = solo archiviata. Omettilo per tutta la posta.
categorystringnoprimary (persone), updates (newsletter, invii massivi, automatici) o spam; oppure un elenco separato da virgole. Lo spam è nascosto se non richiesto.
importantbooleannotrue = solo i messaggi contrassegnati come importanti (risposte a conversazioni avviate da te e mittenti segnati come importanti).
include_spambooleannoIncludi lo spam nei risultati (per ricerche in tutte le cartelle).
fromstringnoL'indirizzo del mittente contiene questo valore.
tostringnoL'indirizzo del destinatario contiene questo valore.
unreadbooleannotrue = solo non letti, false = solo letti.
afterstringnoTimestamp ISO-8601; solo i messaggi creati dopo. (date-time)
beforestringnoTimestamp ISO-8601; solo i messaggi creati prima. (date-time)
querystringnoRicerca a testo libero in oggetti, corpi, indirizzi di mittente/destinatario e nomi file degli allegati. (max 200 caratteri)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [riepiloghi delle email], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}
Sola letturaget_email
GET /emails/:email_id

Recupera un'email

Recupera un messaggio con intestazioni, corpo html/testo, stato, metadati del thread e metadati degli allegati (scarica i byte con download_attachment).

ParametroTipoObbligatorioDescrizione
email_idstringsìID dell'email (inizia con em_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
RestituisceOggetto email: {id, direction, status, from, to, cc, bcc, subject, html, text, threadId, messageId, providerMessageId, readAt, createdAt, attachments: [{id, filename, contentType, sizeBytes, available}]}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}
Modifica lo statomark_email
PATCH /emails/:email_id

Segna come letto, archiviato, spam o importante

Aggiorna un messaggio: read, archived, category (primary, updates, spam; solo posta ricevuta) e important. Segnalare spam o contrassegnare come importante insegna a SendHQ qualcosa su quel mittente per la posta futura; passa learn: false per modificare solo questo messaggio. Passa almeno un campo.

ParametroTipoObbligatorioDescrizione
email_idstringsìID dell'email (inizia con em_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
readbooleannotrue = letto, false = non letto.
archivedbooleannotrue = archivia (salta la Inbox), false = riporta nella Inbox.
categorystringnoSposta un messaggio ricevuto in primary, updates o spam. (uno tra primary, updates, spam)
importantbooleannoContrassegna o rimuovi il contrassegno di importante dal messaggio.
learnbooleannofalse = non memorizzare questa valutazione per il mittente (predefinito true).
RestituisceL'oggetto email aggiornato.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}
Distruttivodelete_email
DELETE /emails/:email_id

Elimina un'email

DESTRUCTIVE: elimina definitivamente da SendHQ un messaggio conservato e i suoi allegati archiviati. Non richiama un messaggio già consegnato.

ParametroTipoObbligatorioDescrizione
email_idstringsìID dell'email (inizia con em_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}
Sola letturalist_email_events
GET /emails/:email_id/events

Elenca gli eventi di consegna di un'email

Eventi del provider per un messaggio inviato: delivery, bounce, complaint, reject, open, click. Sono le prove che dicono se un messaggio è stato consegnato o perché non lo è stato. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
email_idstringsìID dell'email (inizia con em_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [{event_type, recipient, reason, created_at, …}], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}
Sola letturaget_thread
GET /threads/:thread_id

Recupera una conversazione

Recupera tutti i messaggi di una conversazione in ordine cronologico (inviati e ricevuti), ognuno con i metadati degli allegati.

ParametroTipoObbligatorioDescrizione
thread_idstringsìID del thread (di solito l'ID em_… del primo messaggio; vedi threadId su qualsiasi email). (max 128 caratteri)
Restituisce{id, subject, data: [email]}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_thread",
  "arguments": {
    "thread_id": "em_123"
  }
}
Read-onlyemail_delivery
GET /emails/:email_id/delivery

Get an email delivery timeline

Queued, sent, delivered, delayed, bounced, complained, and failed events for one email, with bounce type and the SMTP diagnostic. Reasons are plain text.

ParametroTipoObbligatorioDescrizione
email_idstringsì
limitintegerno
offsetintegerno
Returns{emailId, status, timeline, count, limit, offset}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "email_delivery",
  "arguments": {
    "email_id": "em_123"
  }
}
Read-onlythread_delivery
GET /threads/:thread_id/delivery

Get a thread delivery summary

Counts of delivered, bounced, complained, and failed outbound messages in one conversation, plus each message's failure reason.

ParametroTipoObbligatorioDescrizione
thread_idstringsì
Returns{threadId, delivered, bounced, complained, failed, messages}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "thread_delivery",
  "arguments": {
    "thread_id": "thr_123"
  }
}

Etichette e regole di archiviazione automatica

Sola letturalist_labels
GET /labels

Elenca le etichette

Elenca le etichette (cartelle) del workspace con il numero totale e di non letti e le relative regole di archiviazione automatica. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [{id, name, color, totalCount, unreadCount, rules: [...]}], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_labels",
  "arguments": {}
}
Sola letturaget_label
GET /labels/:label_id

Recupera un'etichetta

Recupera un'etichetta con i conteggi e le regole di archiviazione automatica.

ParametroTipoObbligatorioDescrizione
label_idstringsìID dell'etichetta (inizia con lbl_) o il nome esatto dell'etichetta. (max 128 caratteri)
RestituisceOggetto etichetta.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}
Modifica lo statocreate_label
POST /labels

Crea un'etichetta

Crea un'etichetta in stile cartella. Imposta skip_inbox: true per trasformarla in un bucket di proprietà di un agente: invia con labels: [name] e le risposte vengono archiviate nell'etichetta e tenute fuori dalla Inbox. Le regole facoltative di archiviazione automatica archiviano la nuova posta inviata/ricevuta (ogni condizione di una regola deve corrispondere). Imposta apply_to_existing per archiviare anche la posta già conservata.

ParametroTipoObbligatorioDescrizione
namestringsìNome dell'etichetta, ad es. Billing o Clients/Acme. Univoco per workspace (senza distinzione tra maiuscole e minuscole). (max 64 caratteri)
colorstringnoColore esadecimale, ad esempio #1a73e8. Facoltativo.
skip_inboxbooleannoModalità bucket: la posta ricevuta che ottiene questa etichetta (tramite una regola, rispondendo a una conversazione inviata con questa etichetta o a mano) viene archiviata, così compare solo nell'etichetta e non nella Inbox.
rulesobject[]noRegole facoltative di archiviazione automatica (max 20). Ognuna richiede almeno uno tra inbox_id, from, to, subject. (0–20 elementi)
rules[].directionstringnoSolo posta in (ricevuta) o out (inviata). Omettilo per entrambe. (uno tra in, out)
rules[].inbox_idstringnoSolo la posta ricevuta da questa inbox (inb_…). Archivia ogni indirizzo di ricezione nella propria cartella.
rules[].fromstringnoIl mittente contiene questo testo (senza distinzione tra maiuscole e minuscole), ad es. @stripe.com. (max 200 caratteri)
rules[].tostringnoTo/Cc contiene questo testo (senza distinzione tra maiuscole e minuscole). (max 200 caratteri)
rules[].subjectstringnoL'oggetto contiene questo testo (senza distinzione tra maiuscole e minuscole). (max 200 caratteri)
rules[].skip_inboxbooleannoArchivia la posta ricevuta corrispondente, così compare solo nella cartella dell'etichetta e non nella Inbox.
apply_to_existingbooleannoArchivia anche la posta già conservata che corrisponde alle regole.
RestituisceL'etichetta creata con le regole.
Esempio di params per tools/call
{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}
Modifica lo statoupdate_label
PATCH /labels/:label_id

Rinomina un'etichetta, cambiane il colore o rendila un bucket

Rinomina un'etichetta, cambiane il colore o attiva/disattiva la modalità bucket (skip_inbox). Attivare la modalità bucket archivia la posta ricevuta già presente nell'etichetta.

ParametroTipoObbligatorioDescrizione
label_idstringsìID dell'etichetta (inizia con lbl_) o il nome esatto dell'etichetta. (max 128 caratteri)
namestringnoNuovo nome. (max 64 caratteri)
colorstringnoNuovo colore esadecimale.
skip_inboxbooleannoModalità bucket: la posta ricevuta che ottiene questa etichetta (tramite una regola, rispondendo a una conversazione inviata con questa etichetta o a mano) viene archiviata, così compare solo nell'etichetta e non nella Inbox.
RestituisceL'etichetta aggiornata.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}
Distruttivodelete_label
DELETE /labels/:label_id

Elimina un'etichetta

DESTRUCTIVE: elimina un'etichetta e le sue regole. Le email vengono mantenute; perdono solo questa etichetta.

ParametroTipoObbligatorioDescrizione
label_idstringsìID dell'etichetta (inizia con lbl_) o il nome esatto dell'etichetta. (max 128 caratteri)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}
Modifica lo statocreate_label_rule
POST /labels/:label_id/rules

Aggiungi una regola di archiviazione automatica

Aggiungi una regola a un'etichetta, così la nuova posta corrispondente viene archiviata automaticamente. Ogni condizione impostata deve corrispondere. Usa inbox_id per dare a un indirizzo di ricezione la propria cartella; aggiungi skip_inbox per tenerla fuori dalla Inbox.

ParametroTipoObbligatorioDescrizione
label_idstringsìID dell'etichetta (inizia con lbl_) o il nome esatto dell'etichetta. (max 128 caratteri)
directionstringnoSolo posta in (ricevuta) o out (inviata). Omettilo per entrambe. (uno tra in, out)
inbox_idstringnoSolo la posta ricevuta da questa inbox (inb_…). Archivia ogni indirizzo di ricezione nella propria cartella.
fromstringnoIl mittente contiene questo testo (senza distinzione tra maiuscole e minuscole), ad es. @stripe.com. (max 200 caratteri)
tostringnoTo/Cc contiene questo testo (senza distinzione tra maiuscole e minuscole). (max 200 caratteri)
subjectstringnoL'oggetto contiene questo testo (senza distinzione tra maiuscole e minuscole). (max 200 caratteri)
skip_inboxbooleannoArchivia la posta ricevuta corrispondente, così compare solo nella cartella dell'etichetta e non nella Inbox.
apply_to_existingbooleannoArchivia anche la posta già conservata che corrisponde.
Restituisce{id: lrule_…, labelId, direction, inboxId, from, to, subject, skipInbox}.
Esempio di params per tools/call
{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}
Distruttivodelete_label_rule
DELETE /labels/:label_id/rules/:rule_id

Elimina una regola di archiviazione automatica

DESTRUCTIVE: rimuove una regola di archiviazione automatica. La posta già archiviata mantiene l'etichetta.

ParametroTipoObbligatorioDescrizione
label_idstringsìID dell'etichetta (inizia con lbl_) o il nome esatto dell'etichetta. (max 128 caratteri)
rule_idstringsìID della regola (inizia con lrule_), da get_label. (max 128 caratteri)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}
Modifica lo statolabel_email
POST /emails/:email_id/labels

Aggiungi o rimuovi etichette da un'email

Sposta un messaggio tra cartelle: aggiungi e/o rimuovi etichette per nome o per ID lbl_…. I nomi sconosciuti in add vengono creati, a meno che create sia false.

ParametroTipoObbligatorioDescrizione
email_idstringsìID dell'email (inizia con em_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
addstring[]noEtichette da aggiungere. (0–10 elementi)
removestring[]noEtichette da rimuovere. (0–10 elementi)
createbooleannoCrea le etichette sconosciute in add (predefinito true).
RestituisceL'email aggiornata con labels.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

Bozze, allegati e identità mittente

Sola letturalist_sending_identities
GET /sending-identities

Elenca le identità mittente verificate

Indirizzi e domini da cui questo workspace può inviare in questo momento (domini verificati, il loro From predefinito e gli indirizzi delle inbox attive). Chiamalo prima di send_email per scegliere un from valido.

Nessun parametro.

Restituisce{domains: [nomi dei domini verificati], addresses: [indirizzi mittente], localParts: [...]}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_sending_identities",
  "arguments": {}
}
Modifica lo statocreate_draft
POST /drafts

Crea una bozza

Crea una bozza del composer. Le bozze contengono gli allegati: crea una bozza, chiama upload_attachment, poi send_email con draft_id. Non invia nulla.

ParametroTipoObbligatorioDescrizione
fromstringnoIndirizzo del mittente su un dominio verificato (può essere vuoto durante la stesura).
tostring[]noDestinatari. (0–100 elementi)
ccstring[]noDestinatari in copia. (0–100 elementi)
bccstring[]noDestinatari in copia nascosta. (0–100 elementi)
subjectstringnoOggetto. (max 998 caratteri)
htmlstringnoCorpo HTML.
textstringnoCorpo in testo semplice.
reply_to_email_idstringnoID dell'email a cui risponde questa bozza.
thread_idstringnoID del thread a cui appartiene questa bozza.
RestituisceOggetto bozza {id: dr_…, from, to, cc, bcc, subject, html, text, attachments: []}.
Esempio di params per tools/call
{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}
Sola letturalist_drafts
GET /drafts

Elenca le bozze

Elenca le bozze del composer, dalle aggiornate più di recente. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [bozze], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_drafts",
  "arguments": {}
}
Sola letturaget_draft
GET /drafts/:draft_id

Recupera una bozza

Recupera una bozza con i metadati dei suoi allegati.

ParametroTipoObbligatorioDescrizione
draft_idstringsìID della bozza (inizia con dr_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
RestituisceOggetto bozza con attachments.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
Modifica lo statoupdate_draft
PUT /drafts/:draft_id

Sostituisci il contenuto della bozza

Sostituisce contenuto e destinatari di una bozza. È una sostituzione completa: i campi omessi vengono svuotati, quindi leggi prima get_draft e invia tutti i campi che vuoi mantenere. Gli allegati non vengono toccati.

ParametroTipoObbligatorioDescrizione
draft_idstringsìID della bozza (inizia con dr_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
fromstringnoIndirizzo del mittente su un dominio verificato (può essere vuoto durante la stesura).
tostring[]noDestinatari. (0–100 elementi)
ccstring[]noDestinatari in copia. (0–100 elementi)
bccstring[]noDestinatari in copia nascosta. (0–100 elementi)
subjectstringnoOggetto. (max 998 caratteri)
htmlstringnoCorpo HTML.
textstringnoCorpo in testo semplice.
reply_to_email_idstringnoID dell'email a cui risponde questa bozza.
thread_idstringnoID del thread a cui appartiene questa bozza.
RestituisceOggetto bozza aggiornato.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}
Distruttivodelete_draft
DELETE /drafts/:draft_id

Scarta una bozza

DESTRUCTIVE: scarta una bozza ed elimina definitivamente i suoi allegati archiviati.

ParametroTipoObbligatorioDescrizione
draft_idstringsìID della bozza (inizia con dr_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
Modifica lo statoupload_attachment
POST /drafts/:draft_id/attachments

Carica un allegato in una bozza

Carica un file in una bozza (max 10 file e 10 MB in totale per messaggio). Fornisci content_base64 o un file_path locale. Al momento dell'invio gli allegati richiedono un piano a pagamento.

Fornisci almeno uno tra: content_base64, file_path.

ParametroTipoObbligatorioDescrizione
draft_idstringsìID della bozza (inizia con dr_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
filenamestringnoNome del file mostrato al destinatario. Per impostazione predefinita è il nome base di file_path. (max 255 caratteri)
content_typestringnoTipo MIME, ad es. application/pdf. Predefinito: application/octet-stream.
content_base64stringnoContenuto del file in base64 standard.
file_pathstringnoPercorso assoluto di un file locale leggibile dal processo del server MCP.
Restituisce{id: att_…, filename, contentType, sizeBytes, available}.
Esempio di params per tools/call
{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}
Sola letturadownload_attachment
GET /attachments/:attachment_id

Scarica un allegato

Scarica un allegato privato (inviato, ricevuto o di una bozza). Restituisce il contenuto in base64, oppure scrive il file quando è impostato save_to_path (rifiuta di sovrascrivere a meno che overwrite sia true).

ParametroTipoObbligatorioDescrizione
attachment_idstringsìID dell'allegato (inizia con att_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
save_to_pathstringnoPercorso locale assoluto facoltativo in cui scrivere il file invece di restituirlo in base64.
overwritebooleannoConsente di sostituire un file esistente in save_to_path. Predefinito: false.
Restituisce{attachment_id, filename, content_type, size_bytes, content_base64} oppure {attachment_id, filename, content_type, size_bytes, saved_to}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}
Distruttivodelete_attachment
DELETE /attachments/:attachment_id

Elimina un allegato

DESTRUCTIVE: elimina definitivamente un allegato archiviato (ad esempio per togliere un file da una bozza prima dell'invio).

ParametroTipoObbligatorioDescrizione
attachment_idstringsìID dell'allegato (inizia con att_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

Template ospitati

Sola letturalist_templates
GET /templates

Elenca i template ospitati

Elenca i template email ospitati con stato di pubblicazione e utilizzo. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
lifecyclestringnoactive (predefinito), archived o all. (uno tra active, archived, all)
querystringnoCerca per nome o chiave. (max 120 caratteri)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [template], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}
Modifica lo statocreate_template
POST /templates

Crea un template ospitato

Crea un template con una bozza modificabile, facoltativamente a partire da un modello iniziale (welcome, reset, receipt o blank). Pubblicalo prima di inviare tramite chiave.

ParametroTipoObbligatorioDescrizione
namestringsìNome leggibile. (max 120 caratteri)
keystringnoChiave di invio stabile: lettere minuscole, numeri e trattini; inizia con una lettera (2–64 caratteri). Se omessa, viene ricavata dal nome.
starterstringnoContenuto iniziale. (uno tra blank, welcome, reset, receipt)
Restituisce{template, draft, activeVersion, versions, usage}.
Esempio di params per tools/call
{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}
Sola letturaget_template
GET /templates/:template_id

Recupera un template

Recupera la bozza corrente di un template (con revision), la release pubblicata attiva, lo storico delle release e l'utilizzo. Accetta ID o chiave.

ParametroTipoObbligatorioDescrizione
template_idstringsìID del template (tmpl_…) o chiave. (max 128 caratteri)
Restituisce{template, draft: {id, revision, subjectTemplate, htmlTemplate, textTemplate, variables, sampleData, …} | null, activeVersion, versions, usage}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Modifica lo statoupdate_template_draft
PUT /templates/:template_id/draft

Salva la bozza di un template

Salva la bozza modificabile del template con concorrenza ottimistica: passa la revision corrente ottenuta da get_template (409 significa che qualcun altro ha salvato prima; rileggi e ritenta). È una sostituzione completa del contenuto della bozza: i campi omessi vengono svuotati, quindi invia tutti i campi che vuoi mantenere. Usa i segnaposto {{variable}}.

ParametroTipoObbligatorioDescrizione
template_idstringsìID o chiave del template. (max 128 caratteri)
revisionintegersìRevisione corrente della bozza, da get_template. (1–…)
namestringnoNome del template. (max 120 caratteri)
subject_templatestringnoOggetto con segnaposto. (max 998 caratteri)
preheader_templatestringnoTesto di anteprima. (max 240 caratteri)
html_templatestringnoCorpo HTML con segnaposto.
text_templatestringnoCorpo in testo semplice con segnaposto.
fromstringnoMittente predefinito per gli invii di questo template.
reply_tostringnoReply-To predefinito.
variablesobject[]noContratto delle variabili tipizzate. Ogni elemento: {key (minuscole/underscore), label, type: text|number|url|boolean, required (predefinito true), fallback, description}.
variables[].keystringsì
variables[].labelstringno
variables[].typestringno(uno tra text, number, url, boolean)
variables[].requiredbooleanno
variables[].fallbackanyno
variables[].descriptionstringno
sample_dataobjectnoValori di esempio usati per anteprime e test.
Restituisce{template, draft: {revision: next}, validation: {valid, findings}}.
Esempio di params per tools/call
{
  "name": "update_template_draft",
  "arguments": {
    "template_id": "account-welcome",
    "revision": 3,
    "name": "Account welcome",
    "subject_template": "Welcome, {{first_name}}",
    "text_template": "Hi {{first_name}}",
    "variables": [
      {
        "key": "first_name",
        "type": "text",
        "required": true
      }
    ],
    "sample_data": {
      "first_name": "Asha"
    }
  }
}
Modifica lo statocreate_template_draft
POST /templates/:template_id/draft

Avvia una nuova bozza dalla release pubblicata

Crea una nuova bozza modificabile copiata dalla release pubblicata corrente (409 se esiste già una bozza o se non è pubblicato nulla).

ParametroTipoObbligatorioDescrizione
template_idstringsìID o chiave del template. (max 128 caratteri)
Restituisce{draft}.
Esempio di params per tools/call
{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Sola letturarender_template
POST /templates/:template_id/render

Renderizza l'anteprima di un template

Renderizza l'output esatto del server (oggetto, html, testo) per la bozza, la release pubblicata o una versione specifica con i dati forniti. Non invia nulla. Restituisce 422 con findings quando i dati violano il contratto delle variabili.

ParametroTipoObbligatorioDescrizione
template_idstringsìID o chiave del template. (max 128 caratteri)
version_idstringnoID di versione facoltativo; per impostazione predefinita la bozza, poi la release pubblicata.
dataobjectnoValori delle variabili; per impostazione predefinita i dati di esempio della versione.
Restituisce{subject, html, text, preheader, versionId, versionNumber, isDraft, findings}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}
Invia email realisend_template_test
POST /templates/:template_id/test

Invia un'email di test del template

SENDS REAL EMAIL. Send a [Test]-prefixed snapshot of the draft (or a given version) to the given recipients. Counts against usage; trial workspaces can only send to the account email or a mailbox-simulator test address.

ParametroTipoObbligatorioDescrizione
template_idstringsìID o chiave del template. (max 128 caratteri)
tostring[]sìDestinatari del test. (1–100 elementi)
fromstringnoMittente su un dominio verificato; per impostazione predefinita il From del template.
version_idstringnoID di versione facoltativo.
dataobjectnoValori delle variabili; per impostazione predefinita i dati di esempio.
Restituisce{id: em_…, providerMessageId, threadId, isTest: true}.
Esempio di params per tools/call
{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}
Modifica lo statopublish_template
POST /templates/:template_id/publish

Pubblica una release del template

Pubblica la bozza corrente come release immutabile che verrà usata da send_email con template.key. Fallisce con 422 e i findings in caso di errori di validazione, oppure con 409 se romperebbe il contratto delle variabili attivo di un template già usato in produzione.

ParametroTipoObbligatorioDescrizione
template_idstringsìID o chiave del template. (max 128 caratteri)
Restituisce{template, published}.
Esempio di params per tools/call
{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Modifica lo statoarchive_template
POST /templates/:template_id/archive

Archivia un template

Blocca i nuovi invii che usano questo template (lo storico viene conservato; reversibile con restore_template). Qualsiasi integrazione che invia con questa chiave inizierà a fallire con 404.

ParametroTipoObbligatorioDescrizione
template_idstringsìID o chiave del template. (max 128 caratteri)
Restituisce{template}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Modifica lo statorestore_template
POST /templates/:template_id/restore

Ripristina un template archiviato

Rende di nuovo attivo un template archiviato.

ParametroTipoObbligatorioDescrizione
template_idstringsìID o chiave del template. (max 128 caratteri)
Restituisce{template}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

Domini e DNS

Sola letturalist_domains
GET /domains

Elenca i domini

Elenca i domini di invio con lo setup_status aggregato (verified | checking | pending), lo stato DNS di ogni record e lo stato della ricezione in entrata. Può essere lento: i domini non verificati vengono ricontrollati in tempo reale. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [domini con record], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_domains",
  "arguments": {}
}
Sola letturaget_domain
GET /domains/:domain_id

Recupera i dettagli di configurazione del dominio

Recupera un dominio con i record DNS esatti da pubblicare (tipo, nome, valore), lo stato attuale di ogni record visto da due resolver pubblici, i dns_issues con le correzioni e lo stato della ricezione in entrata.

ParametroTipoObbligatorioDescrizione
domain_idstringsìID del dominio (inizia con dom_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{id, name, status, setup_status, dns_propagating, records: [{type, name, value, verified, dns_state}], dns_issues: [{code, message, …}], inbound_domain, inbound_status}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Modifica lo statoadd_domain
POST /domains

Aggiungi un dominio di invio

Register a domain you control for sending. Returns the DNS records (Easy DKIM CNAMEs) the owner must publish. Does not change DNS itself. Counts against the plan's domain limit.

ParametroTipoObbligatorioDescrizione
namestringsìNome di dominio semplice, ad es. example.com o mail.example.com. (max 253 caratteri)
default_fromstringnoIndirizzo mittente predefinito facoltativo su questo dominio.
Restituisce{id: dom_…, name, status: pending, records: [...], ses: {configured}}.
Esempio di params per tools/call
{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}
Modifica lo statoverify_domain
POST /domains/:domain_id/verify

Verifica un dominio

Run a live DNS and DKIM verification check now. Safe to repeat; poll every 30–60 s after DNS changes (propagation can take minutes to hours). Sending is allowed once status is verified.

ParametroTipoObbligatorioDescrizione
domain_idstringsìID del dominio (inizia con dom_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{domain, checks: {ses, dkim, dkim_status}, status: verified|pending}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Distruttivodelete_domain
DELETE /domains/:domain_id

Elimina un dominio

DESTRUCTIVE: rimuove il dominio dal workspace, compresa la sua route di ricezione in entrata. Gli invii da quel dominio falliscono subito dopo. Non elimina i record DNS presso il tuo provider DNS.

ParametroTipoObbligatorioDescrizione
domain_idstringsìID del dominio (inizia con dom_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Sola letturaget_dns_provider
GET /dns/provider

Rileva il provider DNS e gli host dei record

Rileva il provider DNS autoritativo del dominio e restituisce l'host relativo da inserire presso quel provider per ogni record, il record DMARC consigliato, le indicazioni per l'MX in entrata e se è disponibile la configurazione con un clic (Domain Connect).

ParametroTipoObbligatorioDescrizione
domain_idstringsìID del dominio (inizia con dom_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{detectionStatus, detected, zone, nameservers, recordHosts: {recordId: host}, inbound, recommendations, authentication, providers: {domainConnect: {available, providerName}}}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Email in entrata

Modifica lo statosetup_inbound
POST /domains/:domain_id/inbound/setup

Abilita la ricezione in entrata per un dominio

Provision inbound receiving for a verified domain. Uses the root domain when it has no conflicting MX, otherwise inbound.<domain>. Returns the MX record the owner must publish; it does not edit DNS.

ParametroTipoObbligatorioDescrizione
domain_idstringsìID del dominio (inizia con dom_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{domain: dominio di ricezione, status: dns_pending|ready, record: {type: MX, name, value}}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Modifica lo statoverify_inbound
POST /domains/:domain_id/inbound/verify

Verifica l'MX in entrata

Ricontrolla il record MX in entrata. Lo stato diventa ready quando entrambi i resolver pubblici lo vedono.

ParametroTipoObbligatorioDescrizione
domain_idstringsìID del dominio (inizia con dom_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{domain, status: ready|dns_pending|propagating|checking, record}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Sola letturalist_inboxes
GET /inboxes

Elenca gli indirizzi in entrata

Elenca gli indirizzi di ricezione, facoltativamente per un solo dominio. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
domain_idstringnoFiltro facoltativo per ID del dominio.
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [{id, address, name, status, domainId}], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Sola letturaget_inbox
GET /inboxes/:inbox_id

Recupera una inbox

Recupera un indirizzo in entrata.

ParametroTipoObbligatorioDescrizione
inbox_idstringsìID della inbox (inizia con inb_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
RestituisceOggetto inbox.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}
Modifica lo statocreate_inbox
POST /inboxes

Crea un indirizzo in entrata

Crea un indirizzo come support@<receiving domain> su un dominio con stato di ricezione ready (esegui prima setup_inbound e verify_inbound). La posta ricevuta compare in list_emails con direction in.

ParametroTipoObbligatorioDescrizione
domain_idstringsìID del dominio (inizia con dom_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
local_partstringsìParte prima della @, ad es. support. (max 64 caratteri)
namestringnoNome visualizzato facoltativo.
Restituisce{id: inb_…, address, name, status: active}.
Esempio di params per tools/call
{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}
Modifica lo statoupdate_inbox
PATCH /inboxes/:inbox_id

Rinomina, attiva o disattiva una inbox

Rinomina una inbox o imposta il suo stato su active / disabled.

ParametroTipoObbligatorioDescrizione
inbox_idstringsìID della inbox (inizia con inb_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
namestringnoNuovo nome visualizzato.
statusstringnoNuovo stato. (uno tra active, disabled)
RestituisceLa inbox aggiornata.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}
Invia email realiset_inbox_forwarding
PUT /inboxes/:inbox_id/forwarding

Inoltra una inbox a un altro indirizzo

SENDS REAL EMAIL quando inoltri a una persona diversa dal titolare dell'account: imposta dove viene inoltrata la posta ricevuta da una inbox. L'indirizzo del titolare si attiva subito; qualsiasi altro indirizzo riceve un'email di conferma e l'inoltro resta pending finché qualcuno non conferma da quell'indirizzo. Passa forward_to: null per disattivare l'inoltro. Le copie inoltrate partono dall'indirizzo della inbox con il mittente originale come Reply-To.

ParametroTipoObbligatorioDescrizione
inbox_idstringsìID della inbox (inizia con inb_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
forward_tostring,nullsìIndirizzo email di destinazione dell'inoltro, oppure null per disattivarlo. (max 254 caratteri)
RestituisceLa inbox con forwardTo e forwardStatus (off, pending o active).
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}
Distruttivodelete_inbox
DELETE /inboxes/:inbox_id

Elimina una inbox

DESTRUCTIVE: elimina un indirizzo in entrata. La posta già ricevuta viene conservata; la nuova posta diretta all'indirizzo non viene più archiviata lì.

ParametroTipoObbligatorioDescrizione
inbox_idstringsìID della inbox (inizia con inb_), come restituito da uno strumento di elenco o di creazione. (max 128 caratteri)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

Deliverability, bounce e soppressioni

Sola letturadeliverability_stats
GET /deliverability/stats

Recupera le statistiche di consegna degli ultimi 30 giorni

Totali degli ultimi 30 giorni per l'intero workspace: sent, delivery, bounce, complaint, reject, open, click e deliveryRate (%).

Nessun parametro.

Restituisce{window: 30d, sent, delivery, bounce, complaint, reject, open, click, deliveryRate}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "deliverability_stats",
  "arguments": {}
}
Read-onlydeliverability_account
GET /deliverability/account

Get account delivery rates

Daily ladder, today's usage, 7-day hard-bounce and complaint rates against the promote, hold, and pause thresholds, and a per-day trend. Diagnostic text is plain text.

ParametroTipoObbligatorioDescrizione
daysintegerno(one of 7, 30, 90)
Returns{days, trend, rolling7d, thresholds, ladder}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "deliverability_account",
  "arguments": {
    "days": 30
  }
}
Read-onlydeliverability_domains
GET /deliverability/domains

Get domain delivery rates

Per sending domain: sent, delivered, hard and soft bounces, complaints, failures, rates, and an active Gmail cap or 4.7.28 backoff when one applies.

ParametroTipoObbligatorioDescrizione
daysintegerno
domainstringno
limitintegerno
offsetintegerno
Returns{days, data, count, limit, offset}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "deliverability_domains",
  "arguments": {
    "days": 30
  }
}
Read-onlydeliverability_senders
GET /deliverability/senders

Get sender delivery rates

Per From address: sent, delivered, hard and soft bounces, complaints, failures, and rates.

ParametroTipoObbligatorioDescrizione
daysintegerno
domainstringno
limitintegerno
offsetintegerno
Returns{days, data, count, limit, offset}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "deliverability_senders",
  "arguments": {
    "days": 30
  }
}
Read-onlyscore_email
POST /deliverability/score

Score an email's content

A checklist of one email's content before it is sent: 100 for a plain email with no links and no images, lower for each thing mail filters look at (a designed layout, links to another site than the sender's, link shorteners, images with few words, hidden text, capitals, an empty subject, very long HTML). Returns each finding with the points it costs and a one-line suggestion, most points first. Read-only: nothing is stored or sent. Pass the email as written; the unsubscribe footer and tracking SendHQ adds are not scored. It looks at content only: sender reputation, authentication and how recipients react decide more of where mail lands, so treat it as a checklist, not a prediction.

ParametroTipoObbligatorioDescrizione
subjectstringnoThe subject line.
htmlstringnoThe HTML as written, before SendHQ adds its footer or tracking. (max 2000000 chars)
textstringnoThe plain-text part. Compared with the HTML when both are given; scored on its own when there is no HTML. (max 2000000 chars)
fromstringnoThe sender: an email address or a domain such as example.com. Without it, links to other sites are not judged. (max 320 chars)
Returns{score (0 to 100), deductions: [{id, points, count, suggestion}], warnings: [{id, message}]}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "score_email",
  "arguments": {
    "from": "hello@example.com",
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p><p><a href=\"https://bit.ly/3xyz\">Finish checkout</a></p>"
  }
}
Sola letturalist_sender_reputation
GET /deliverability/reputation

Elenca la reputazione dei mittenti

Stato della reputazione per indirizzo From esatto: active, throttled (limite giornaliero ridotto) o paused (gli invii restituiscono 423), con il motivo e il limite giornaliero. Controllalo quando gli invii falliscono con 423 o 429. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [{sender, status, dailyLimit, reason, cleanSince, warnedAt, pausedAt, evaluatedAt}], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_sender_reputation",
  "arguments": {}
}
Sola letturalist_suppressions
GET /suppressions

Elenca le soppressioni

Lista di soppressione del workspace: destinatari bloccati dopo un bounce permanente o una segnalazione di spam. Gli invii verso di loro falliscono con 422. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [{email, reason, detail, created_at}], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_suppressions",
  "arguments": {}
}
Distruttivoremove_suppression
DELETE /suppressions/:email

Rimuovi una soppressione per bounce

DESTRUCTIVE (indebolisce un blocco di sicurezza): rimuove una soppressione per bounce, così l'indirizzo può ricevere di nuovo posta. Fallo solo quando la persona conferma che l'indirizzo ora è valido. Le soppressioni per segnalazione di spam non possono essere rimosse (409).

ParametroTipoObbligatorioDescrizione
emailstringsìIndirizzo del destinatario soppresso. (max 320 caratteri)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}
Sola letturalist_blocked_recipients
GET /blocked-recipients

Elenca i destinatari bloccati

Tutti i destinatari che SendHQ rifiuterà: bounce, segnalazioni di spam e disiscrizioni dal marketing a livello di dominio, con un riepilogo per tipo. Legge fino ai 500 più recenti. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [{email, domain, kind: bounce|complaint|unsubscribe, reason, detail, source, status, created_at}], count, summary: {total, bounce, complaint, unsubscribe}, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_blocked_recipients",
  "arguments": {}
}

Campaigns

Read-onlylist_contacts
GET /contacts

List contacts

Campaigns: Newest-first contacts with their status, consent evidence, tags, custom fields, engagement (bot-filtered, estimated opens and clicks), and the lists they are subscribed to. Filter by list, status (including dormant), email/name substring (* is an email wildcard, e.g. *@example.com), tag, source, signup date, or a saved segment. Paginated: the result includes pagination {offset, limit, returned, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
list_idstringnoOnly members of this list (lst_…).
statusstringnoOnly contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant)
querystringnoEmail or name contains this text; * is a wildcard on the email. (max 200 chars)
tagstringnoOnly contacts with this tag. (max 60 chars)
sourcestringnoHow the contact was added. (one of form, api, import)
afterstringnoSigned up at or after this time. ISO 8601 date or date-time. (max 40 chars)
beforestringnoSigned up before this time. ISO 8601 date or date-time. (max 40 chars)
segment_idstringnoOnly contacts matching this saved segment (seg_…).
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [contacts with tags, engagement, dormant, country], count, total, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_contacts",
  "arguments": {
    "status": "subscribed"
  }
}
Changes statecreate_contact
POST /contacts

Add a contact

Campaigns: Add one contact to the workspace, optionally to lists and with tags. A subscribed contact (the default) needs consent_basis: how this person agreed to receive your email. Only add people who asked for your email. Use status: unsubscribed to record an opt-out. Addresses already suppressed or unsubscribed from the workspace are stored with that status. Fails with 409 if the email already exists.

ParametroTipoObbligatorioDescrizione
emailstringsìEmail address. (max 320 chars)
namestringnoDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectnoCustom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field.
tagsstring[]noTags to attach, e.g. ["VIP"]. Up to 50. (0–50 items)
list_idsstring[]noLists to add the contact to (lst_…). (0–100 items)
statusstringnosubscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed)
consent_basisstringnoHow these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars)
ReturnsThe contact.
Esempio di params per tools/call
{
  "name": "create_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "consent_basis": "Ticked the newsletter box at checkout on acme.com"
  }
}
Changes stateupsert_contact
PUT /contacts

Create or update a contact by email

Campaigns: Create the contact with this email, or change the one that exists: set name, timezone, and locale, merge fields, and add tags. A new contact needs consent_basis and takes the status its address already has (bounced or complained when suppressed, unsubscribed when it opted out, otherwise subscribed). An existing contact's status is never changed, so nobody is resubscribed. Unlike create_contact it does not fail when the email exists. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
emailstringsìEmail address. (max 320 chars)
namestringnoDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectnoCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
tagsstring[]noTags to add, e.g. ["VIP"]. Existing tags are kept. (0–50 items)
timezonestringnoIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
localestringnoLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
consent_basisstringnoHow this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars)
ReturnsThe contact, plus timezone, locale, and created (true when it did not exist before).
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "upsert_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "fields": {
      "plan": "pro"
    },
    "timezone": "Europe/London",
    "consent_basis": "Created an account on acme.com and accepted product emails"
  }
}
Read-onlyget_contact
GET /contacts/:contact_id

Get a contact

Campaigns: One contact by ID or email: status, consent evidence (source, basis, opt-in and confirmation times), custom fields, and subscribed lists.

ParametroTipoObbligatorioDescrizione
contact_idstringsìContact ID (starts with ct_) or the contact's email address. (max 320 chars)
ReturnsThe contact.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}
Changes stateupdate_contact
PATCH /contacts/:contact_id

Update, tag, or unsubscribe a contact

Campaigns: Change a contact's name, merge custom fields (null removes one), change tags (tags replaces the whole set; add_tags and remove_tags change it), or set status to unsubscribed. A contact can never be resubscribed through the API; only the recipient can, by confirming a signup form.

ParametroTipoObbligatorioDescrizione
contact_idstringsìContact ID (starts with ct_) or the contact's email address. (max 320 chars)
namestringnoNew display name. (max 200 chars)
fieldsobjectnoCustom fields (string, number, or boolean values), e.g. {"plan": "pro"}. Usable in broadcasts as {{fields.plan}} or {{plan}}. On update, a null value removes the field.
tagsstring[]noReplace all of the contact's tags with these. (0–50 items)
add_tagsstring[]noTags to add. (0–50 items)
remove_tagsstring[]noTags to remove. (0–50 items)
statusstringnoOnly unsubscribed is accepted. (one of unsubscribed)
ReturnsThe updated contact.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_contact",
  "arguments": {
    "contact_id": "ct_123",
    "fields": {
      "plan": "team"
    }
  }
}
Destructivedelete_contact
DELETE /contacts/:contact_id

Delete a contact

DESTRUCTIVE: permanently delete a contact and its list memberships. Suppressions and recorded unsubscribes are kept, so the address still cannot be mailed if it is added again. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
contact_idstringsìContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}
Changes stateimport_contacts
POST /contact-imports

Import contacts from CSV

Campaigns: Import up to 5,000 CSV rows (5 MB) per call, optionally into a list. The header row needs an email column; name (or first_name/last_name), status, and tags (separated by ; or |) are recognized and other columns become custom fields. consent_basis is required and recorded on every new contact. tags are added to every accepted row. Rows whose status says unsubscribed import as unsubscribed; existing contacts keep their status. Returns counts of accepted, created, existing, skipped (duplicates), and invalid rows with line numbers.

ParametroTipoObbligatorioDescrizione
csvstringsìThe CSV file content, header row first. (max 5242880 chars)
list_idstringnoAdd every accepted row to this list (lst_…).
consent_basisstringsìHow these people agreed to receive your email, recorded as consent evidence, e.g. Signed up on acme.com/newsletter (double opt-in), exported from Mailchimp. 10-500 characters. (max 500 chars)
tagsstring[]noTags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items)
update_existingbooleannoMerge names and fields into contacts that already exist. Their status never changes.
Returns{id, accepted, created, existing, skipped, invalid, errors: [{line, reason}], tags}.
Esempio di params per tools/call
{
  "name": "import_contacts",
  "arguments": {
    "csv": "email,name\nada@example.net,Ada Lovelace\n",
    "consent_basis": "Newsletter signups exported from Mailchimp (double opt-in)"
  }
}
Read-onlylist_contact_imports
GET /contact-imports

List contact imports

Campaigns: Recent CSV imports with their consent basis and row counts.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [imports], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_contact_imports",
  "arguments": {}
}
Destructivebulk_update_contacts
POST /contacts/bulk

Bulk update contacts

DESTRUCTIVE when action is delete (permanent) or unsubscribe (cannot be undone through the API). Apply one action to up to 10,000 contacts: the IDs in contact_ids, or everyone matching filter (the list_contacts filters). Actions: tag / untag (with tags), add_to_list / remove_from_list (with list_id), unsubscribe, delete. Adding to a list mirrors each contact's status, so nobody is resubscribed. delete needs confirm_count equal to the number of contacts it would delete: call once without it to get that count (409), confirm with the user, then repeat with it. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
actionstringsìWhat to do. (one of tag, untag, add_to_list, remove_from_list, unsubscribe, delete)
contact_idsstring[]noContact IDs (ct_…). Use this or filter. (0–10000 items)
filterobjectnoEveryone matching these list_contacts filters. Use this or contact_ids.
filter.list_idstringnoMembers of this list.
filter.statusstringnoOnly contacts with this status. dormant: stopped opening and did not answer list cleanup, so broadcasts skip them. (one of subscribed, pending, unsubscribed, bounced, complained, dormant)
filter.querystringnoEmail or name contains; * is an email wildcard. (max 200 chars)
filter.tagstringnoHas this tag. (max 60 chars)
filter.sourcestringnoHow the contact was added. (one of form, api, import)
filter.afterstringnoSigned up at or after. ISO 8601 date or date-time. (max 40 chars)
filter.beforestringnoSigned up before. ISO 8601 date or date-time. (max 40 chars)
filter.segment_idstringnoMatches this segment.
tagsstring[]noFor tag and untag. (0–50 items)
list_idstringnoFor add_to_list and remove_from_list (lst_…).
confirm_countintegernoFor delete: the number of contacts that will be deleted, from the 409 response. (0–…)
Returns{ok, action, count}; for an unconfirmed delete, a 409 error whose message gives the count.
AnnotationsdestructiveHint
Esempio di params per tools/call
{
  "name": "bulk_update_contacts",
  "arguments": {
    "action": "tag",
    "tags": [
      "october"
    ],
    "filter": {
      "list_id": "lst_123",
      "status": "subscribed"
    }
  }
}
Read-onlylist_tags
GET /tags

List contact tags

Campaigns: The workspace's contact tags, most used first, with how many contacts carry each (up to 500). Paginated.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{tag, count}], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_tags",
  "arguments": {}
}
Read-onlylist_contact_fields
GET /contact-fields

List custom contact fields

Campaigns: Defined custom contact fields with label and type (text, number, date). Defined fields are known to check_broadcast's merge-tag check and typed in segment conditions. Contacts may also carry undefined keys. Paginated.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{key, label, type, createdAt}], count, types, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_contact_fields",
  "arguments": {}
}
Changes stateset_contact_field
PUT /contact-fields/:field_key

Define a custom contact field

Campaigns: Create or change a custom field definition (label and type). Values live on each contact's fields. Built-in merge tags (email, name, first_name, last_name, fields, unsubscribe_url) cannot be used as keys. A workspace may define 50 fields.

ParametroTipoObbligatorioDescrizione
field_keystringsìField key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars)
labelstringnoLabel shown in the dashboard. Defaults to the key. (max 80 chars)
typestringnotext (default), number, or date. (one of text, number, date)
Returns{key, label, type, createdAt}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "set_contact_field",
  "arguments": {
    "field_key": "plan",
    "label": "Plan",
    "type": "text"
  }
}
Destructivedelete_contact_field
DELETE /contact-fields/:field_key

Delete a custom field definition

DESTRUCTIVE: delete a custom field definition. Values already stored on contacts are kept. Fails with 404 when the field is not defined. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
field_keystringsìField key: a lowercase letter, then up to 39 of a-z, 0-9, and _ (e.g. plan). Used in content as {{fields.plan}}. (max 40 chars)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_contact_field",
  "arguments": {
    "field_key": "plan"
  }
}
Read-onlylist_segments
GET /segments

List segments

Campaigns: Saved segments with count (subscribed, non-dormant contacts in the workspace that match now) and fields, the condition fields and operators each accepts. Paginated.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{id, name, match, conditions, count}], count, fields, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_segments",
  "arguments": {}
}
Read-onlyget_segment
GET /segments/:segment_id

Get a segment

Campaigns: One segment with its conditions and live count.

ParametroTipoObbligatorioDescrizione
segment_idstringsìSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Returns{id, name, match, conditions, count}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}
Read-onlypreview_segment
POST /segments/preview

Preview segment conditions

Campaigns: Count and sample (up to 5) the subscribed, non-dormant contacts that match conditions without saving them. Read-only; use it to check conditions before create_segment.

ParametroTipoObbligatorioDescrizione
matchstringnoall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]noUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringsìtag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystringnoCustom field key when field is field. (max 40 chars)
conditions[].opstringsìtag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,numbernoRequired except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
Returns{count, sample: [contacts]}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "preview_segment",
  "arguments": {
    "match": "all",
    "conditions": [
      {
        "field": "tag",
        "op": "has",
        "value": "VIP"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}
Changes statecreate_segment
POST /segments

Create a segment

Campaigns: Save a segment: up to 20 conditions joined by match. Use it as a broadcast's audience.segment_id, as list_contacts segment_id, or in bulk_update_contacts filters. A workspace may have 200 segments.

ParametroTipoObbligatorioDescrizione
namestringsìSegment name. (max 120 chars)
matchstringnoall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]noUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringsìtag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystringnoCustom field key when field is field. (max 40 chars)
conditions[].opstringsìtag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,numbernoRequired except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
ReturnsThe segment with its count.
Esempio di params per tools/call
{
  "name": "create_segment",
  "arguments": {
    "name": "Engaged pro customers",
    "conditions": [
      {
        "field": "fields.plan",
        "op": "equals",
        "value": "pro"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}
Changes stateupdate_segment
PATCH /segments/:segment_id

Update a segment

Campaigns: Rename a segment or change match or conditions (which replaces the whole list). Broadcasts using it pick up the change when they start sending.

ParametroTipoObbligatorioDescrizione
segment_idstringsìSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
namestringnoSegment name. (max 120 chars)
matchstringnoall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]noUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringsìtag, list, status, source, email, name, signed_up, opened, clicked, opens, sends_without_open, country, or a custom field as fields.<key> (or field together with key). (max 48 chars)
conditions[].keystringnoCustom field key when field is field. (max 40 chars)
conditions[].opstringsìtag: has, not_has. list: in, not_in (a list ID). status: is, is_not (subscribed, pending, unsubscribed, bounced, complained, dormant). source: is, is_not (form, api, import). email: contains, not_contains, ends_with. name: is_set, not_set. signed_up: before, after (YYYY-MM-DD), in_last_days, not_in_last_days. opened / clicked: in_last_days, not_in_last_days, ever, never. opens / sends_without_open: gte, lte. country: is, is_not (two-letter code). Custom fields: equals, not_equals, contains, gt, lt, before, after, is_set, not_set. (one of has, not_has, in, not_in, is, is_not, contains, not_contains, ends_with, is_set, not_set, before, after, in_last_days, not_in_last_days, ever, never, gte, lte, equals, not_equals, gt, lt)
conditions[].valuestring,numbernoRequired except for is_set, not_set, ever, and never. A number of days for in_last_days / not_in_last_days, a number for gte, lte, gt, lt, a date (YYYY-MM-DD) for before / after.
ReturnsThe updated segment with its count.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_segment",
  "arguments": {
    "segment_id": "seg_123",
    "name": "Pro customers"
  }
}
Destructivedelete_segment
DELETE /segments/:segment_id

Delete a segment

DESTRUCTIVE: delete a saved segment. Contacts are not affected. Fails with 409 while a sending or scheduled broadcast uses it. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
segment_idstringsìSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}
Read-onlylist_lists
GET /lists

List contact lists

Campaigns: Contact lists with subscribed, pending, and unsubscribed counts and their hosted signup form settings.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [lists], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_lists",
  "arguments": {}
}
Changes statecreate_list
POST /lists

Create a list

Campaigns: Create a contact list. Set form_enabled to publish a hosted double opt-in signup form (its URL is in form.url); form_from is the sender, on a verified domain, of the confirmation email, and redirect_url is an optional https page shown after confirming. welcome sends one welcome email when someone confirms. site publishes a public newsletter site at https://sendhq.cc/n/<slug> with the signup form, sent issues, and RSS.

ParametroTipoObbligatorioDescrizione
namestringsìList name, shown on the signup form. (max 200 chars)
descriptionstringnoShort description shown on the signup form. (max 500 chars)
form_enabledbooleannoPublish the hosted signup form.
form_fromstringnoSender of signup confirmation emails, e.g. Acme <news@example.com>, on a verified domain. (max 320 chars)
redirect_urlstringnohttps page to open after a signup is confirmed. (max 500 chars)
welcomeobjectnoWelcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledbooleannoSend it.
welcome.subjectstringnoSubject; merge tags allowed. (max 300 chars)
welcome.htmlstringnoHTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstringnoMarkdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobjectnoPublic newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409.
site.enabledbooleannoPublish the site.
site.slugstring,nullnoAddress after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,nullnoSite title. Defaults to the list name. (max 120 chars)
site.descriptionstring,nullnoShort description under the title. (max 300 chars)
site.accentstring,nullnoAccent color, e.g. #0a7d4f.
ReturnsThe list.
Esempio di params per tools/call
{
  "name": "create_list",
  "arguments": {
    "name": "Product updates"
  }
}
Read-onlyget_list
GET /lists/:list_id

Get a list

Campaigns: One list with member counts and signup form settings.

ParametroTipoObbligatorioDescrizione
list_idstringsìList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
ReturnsThe list.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_list",
  "arguments": {
    "list_id": "lst_123"
  }
}
Changes stateupdate_list
PATCH /lists/:list_id

Update a list

Campaigns: Rename a list, change its description, or change its hosted signup form, welcome email, or newsletter site. Omitted keys inside welcome and site keep their value.

ParametroTipoObbligatorioDescrizione
list_idstringsìList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
namestringnoNew name. (max 200 chars)
descriptionstringnoNew description. (max 500 chars)
form_enabledbooleannoPublish or unpublish the hosted signup form.
form_fromstringnoSender of signup confirmation emails, on a verified domain. (max 320 chars)
redirect_urlstringnohttps page to open after a signup is confirmed. (max 500 chars)
welcomeobjectnoWelcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledbooleannoSend it.
welcome.subjectstringnoSubject; merge tags allowed. (max 300 chars)
welcome.htmlstringnoHTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstringnoMarkdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobjectnoPublic newsletter site at https://sendhq.cc/n/<slug>: a signup form, every issue sent with web.enabled, and an RSS feed at /n/<slug>/feed.xml. Needs the signup form on. A reserved or taken slug fails with 409.
site.enabledbooleannoPublish the site.
site.slugstring,nullnoAddress after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,nullnoSite title. Defaults to the list name. (max 120 chars)
site.descriptionstring,nullnoShort description under the title. (max 300 chars)
site.accentstring,nullnoAccent color, e.g. #0a7d4f.
ReturnsThe updated list.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_list",
  "arguments": {
    "list_id": "lst_123",
    "form_enabled": false
  }
}
Destructivedelete_list
DELETE /lists/:list_id

Delete a list

DESTRUCTIVE: delete a list and its memberships. The contacts themselves are kept. Fails with 409 while a broadcast to the list is sending. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
list_idstringsìList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_list",
  "arguments": {
    "list_id": "lst_123"
  }
}
Changes stateadd_list_contacts
POST /lists/:list_id/contacts

Add contacts to a list

Campaigns: Add up to 500 existing contacts to a list by ID or email. Subscribed contacts join subscribed; others join in their current state. Unknown references come back in notFound.

ParametroTipoObbligatorioDescrizione
list_idstringsìList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idsstring[]noContact IDs (ct_…). (0–500 items)
emailsstring[]noContact email addresses. (0–500 items)
Returns{listId, added, notFound, list}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "add_list_contacts",
  "arguments": {
    "list_id": "lst_123",
    "emails": [
      "ada@example.net"
    ]
  }
}
Destructiveremove_list_contact
DELETE /lists/:list_id/contacts/:contact_id

Remove a contact from a list

DESTRUCTIVE: remove one contact from a list. The contact and its status are kept. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
list_idstringsìList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idstringsìContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "remove_list_contact",
  "arguments": {
    "list_id": "lst_123",
    "contact_id": "ct_123"
  }
}
Read-onlylist_broadcasts
GET /broadcasts

List broadcasts

Campaigns: Newest-first broadcasts with their status. Paginated: the result includes pagination.

ParametroTipoObbligatorioDescrizione
statusstringnoOnly broadcasts with this status. (one of draft, sending, sent, cancelled, failed)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [broadcasts], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_broadcasts",
  "arguments": {}
}
Changes statecreate_broadcast
POST /broadcasts

Create a broadcast draft

Campaigns: Create a draft broadcast to one list. Content is html and/or text, markdown, a block document in content, or a published hosted template. Raw content supports merge tags: {{first_name}}, {{name}}, {{email}}, {{fields.plan}}, with fallbacks like {{first_name | there}}. audience narrows it to a segment and/or a number of people (most engaged first with order: engaged); tracking turns open and click tracking off; web publishes it on the list's newsletter site once sent. Nothing is sent until send_broadcast or schedule_broadcast; run check_broadcast and send_broadcast_test first.

ParametroTipoObbligatorioDescrizione
namestringnoInternal name. Defaults to the subject. (max 200 chars)
list_idstringnoThe list to send to (lst_…).
fromstringnoSender on a verified domain, e.g. Acme <news@example.com>. (max 320 chars)
reply_tostringnoReply-To address. (max 320 chars)
subjectstringnoSubject line; merge tags allowed. (max 998 chars)
preview_textstringnoInbox preview text shown after the subject. (max 300 chars)
htmlstringnoHTML body; merge tags allowed and escaped.
textstringnoPlain-text body; merge tags allowed.
templateobjectnoA published hosted template instead of subject/html/text. Template variables are filled from the contact's name, email, and fields.
template.idstringno
template.keystringno
template.version_idstringno
markdownstringnoMarkdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars)
contentobject,nullnoBlock document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent.
editorstringnoWhich editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobjectnoWho gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,nullnoOnly list members matching this segment (seg_…), or null for the whole list.
audience.orderstringnoWith a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,nullnoSend to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobjectnoOpen and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensbooleannoAdd an open pixel.
tracking.clicksbooleannoRewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobjectnoPublish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledbooleannoPublish it.
web.slugstring,nullnoIssue address; defaults to the subject. (max 100 chars)
web.pinnedbooleannoKeep it at the top of the site.
ReturnsThe draft broadcast.
Esempio di params per tools/call
{
  "name": "create_broadcast",
  "arguments": {
    "list_id": "lst_123",
    "from": "news@example.com",
    "subject": "October update",
    "markdown": "Hi {{first_name | there}}, here's what shipped.",
    "audience": {
      "order": "engaged",
      "limit": 1000
    }
  }
}
Read-onlyget_broadcast
GET /broadcasts/:broadcast_id

Get a broadcast

Campaigns: One broadcast with its content and, once sending, recipient totals (queued, sending, sent, held, skipped, failed). While a limit or reputation pause holds delivery, lastError explains why and nextAttemptAt says when it resumes.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe broadcast.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Changes stateupdate_broadcast
PATCH /broadcasts/:broadcast_id

Edit a draft broadcast

Campaigns: Change any field of an unscheduled draft broadcast (content, audience, tracking, web). A scheduled draft must be unscheduled first (unschedule_broadcast); sent or sending broadcasts cannot be edited.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
namestringnoInternal name. (max 200 chars)
list_idstringnoThe list to send to.
fromstringnoSender on a verified domain. (max 320 chars)
reply_tostringnoReply-To address. (max 320 chars)
subjectstringnoOggetto. (max 998 caratteri)
preview_textstringnoInbox preview text. (max 300 chars)
htmlstringnoCorpo HTML.
textstringnoCorpo in testo semplice.
templateobject,nullnoA published hosted template, or null to remove it.
markdownstringnoMarkdown body instead of html: converted to a block document and rendered with the workspace design (get_newsletter_settings). Merge tags allowed. Not combinable with html or content. (max 1000000 chars)
contentobject,nullnoBlock document ({"type": "doc", "content": [...]}, the dashboard editor's format: paragraph, heading, bulletList, orderedList, blockquote, image, button, callout, horizontalRule, codeBlock). Rendered with the workspace design unless html is also sent.
editorstringnoWhich editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobjectnoWho gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,nullnoOnly list members matching this segment (seg_…), or null for the whole list.
audience.orderstringnoWith a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,nullnoSend to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobjectnoOpen and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensbooleannoAdd an open pixel.
tracking.clicksbooleannoRewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobjectnoPublish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledbooleannoPublish it.
web.slugstring,nullnoIssue address; defaults to the subject. (max 100 chars)
web.pinnedbooleannoKeep it at the top of the site.
ReturnsThe updated draft.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "subject": "October product update"
  }
}
Destructivedelete_broadcast
DELETE /broadcasts/:broadcast_id

Delete a draft broadcast

DESTRUCTIVE: permanently delete a draft broadcast. Broadcasts that were sent cannot be deleted. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast
POST /broadcasts/:broadcast_id/send

Send a broadcast

SENDS REAL EMAIL to the broadcast's audience: every subscribed, non-dormant member of its list, narrowed by its segment and limit. Only call it when the user asked to send this broadcast now. Each message goes through the normal checks (verified domain, marketing plan, suppressions, unsubscribes, reputation, daily and monthly limits) and carries one-click unsubscribe from this list; members that cannot be mailed are skipped. Each contact is sent at most once. Delivery continues in the background: poll get_broadcast for totals and get_broadcast_report for engagement. A scheduled broadcast fails with 409 until unscheduled. Unpaid workspaces (integration trial) can send only to the account email. Pass idempotency_key so a retry cannot start the send twice. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
idempotency_keystringnoIntestazione Idempotency-Key (max 200 caratteri). Riutilizzala solo per ritentare esattamente questa richiesta. (max 200 caratteri)
ReturnsThe broadcast with status sending and totals.
Esempio di params per tools/call
{
  "name": "send_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "idempotency_key": "october-update"
  }
}
Destructivecancel_broadcast
POST /broadcasts/:broadcast_id/cancel

Cancel a broadcast

DESTRUCTIVE: stop a draft or sending broadcast for good. Recipients not yet sent are marked skipped; messages already handed to the provider are not recalled. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe cancelled broadcast with totals.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "cancel_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Read-onlylist_broadcast_recipients
GET /broadcasts/:broadcast_id/recipients

List broadcast recipients

Campaigns: Per-recipient outcomes and engagement of a broadcast: queued, sending, sent, held, skipped (with the reason), or failed (with the error), the inbox provider, delivered/opened/clicked/bounced/complained/unsubscribed times, and the email ID to inspect delivery events with list_email_events. Filter by outcome, by activity (who opened, clicked, did not open, ...), or by email. Opens are bot-filtered estimates, never proof of reading. Paginated.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
statusstringnoOnly recipients with this outcome. (one of queued, sending, sent, held, skipped, failed)
activitystringnoOnly recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed)
querystringnoRecipient email contains this text. (max 200 chars)
includestringnolinks adds the links each recipient clicked (implied by activity: clicked). (one of links)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{contactId, email, status, skipReason, emailId, error, provider, deliveredAt, openedAt, clickedAt, opens, clicks, bouncedAt, complainedAt, unsubscribedAt, links?}], count, totals, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_broadcast_recipients",
  "arguments": {
    "broadcast_id": "bc_123",
    "status": "failed"
  }
}
Read-onlycheck_broadcast
GET /broadcasts/:broadcast_id/checks

Run a broadcast's pre-send checks

Campaigns: The review list shown before sending: sender verification, subject, preview text, content, audience size, size against Gmail's 102 KB clipping limit, postal address, merge tags without data or fallback, empty or shortened links, image descriptions, placeholder text, spam-prone wording, the trial's own-address rule, and whether a test was sent. ready is false while any check has level block; schedule_broadcast refuses then. Fix warn items or tell the user about them.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Returns{ready, checks: [{id, level: ok|warn|block, label, detail}], audience: {total, matching}}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "check_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast_test
POST /broadcasts/:broadcast_id/test

Send a broadcast test

SENDS REAL EMAIL: a copy of the draft marked [Test] to up to 5 addresses (default: the saved test recipients, or the account email), with merge tags filled from contact_id or a sample contact. Never goes to the list. Only send to addresses the user gave or owns. Limited to 100 test sends a day. Template broadcasts are tested with send_template_test. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
tostring[]noTest recipients (up to 5). (1–5 items)
contact_idstringnoFill merge tags from this contact (ct_…). (max 320 chars)
rememberbooleannoSave to as the default test recipients.
Returns{data: [{to, id, status: sent|failed, error?}]}.
Esempio di params per tools/call
{
  "name": "send_broadcast_test",
  "arguments": {
    "broadcast_id": "bc_123",
    "to": [
      "owner@example.com"
    ]
  }
}
Sends real emailschedule_broadcast
POST /broadcasts/:broadcast_id/schedule

Schedule a broadcast

SENDS REAL EMAIL at scheduled_at to the broadcast's audience, with the same checks as send_broadcast. Only call it when the user asked to send this broadcast at that time. The pre-send checks run now (422 with checks if one blocks). It starts within about a minute of the time; if it can no longer send then, it returns to a draft with the reason in lastError. A scheduled draft cannot be edited until unschedule_broadcast. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
scheduled_atstringsìWhen to send: ISO 8601 date-time with a timezone, at least a minute and at most a year ahead, e.g. 2026-11-10T09:00:00Z. (max 40 chars)
ReturnsThe broadcast with scheduledAt.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "schedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "scheduled_at": "2026-11-10T09:00:00Z"
  }
}
Changes stateunschedule_broadcast
POST /broadcasts/:broadcast_id/unschedule

Unschedule a broadcast

Campaigns: Return a scheduled broadcast to an editable draft so it does not send. Fails with 409 when it is not scheduled.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe draft broadcast.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "unschedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Changes stateduplicate_broadcast
POST /broadcasts/:broadcast_id/duplicate

Duplicate a broadcast

Campaigns: Copy any broadcast (draft, sent, or cancelled) into a new draft named <name> (copy) with the same list, sender, content, audience, and tracking settings. Nothing is sent.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe new draft broadcast.
Esempio di params per tools/call
{
  "name": "duplicate_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Sends real emailsend_broadcast_to_more
POST /broadcasts/:broadcast_id/send-more

Send a broadcast to more people

SENDS REAL EMAIL: sends a sent or sending broadcast to up to limit more people in its audience who have not received it (the rest of a limited audience, or people who joined since), in its audience order. Only call it when the user asked for this. Same checks as send_broadcast; each contact still gets it at most once. Fails with 422 when everyone already got it. Pass idempotency_key so a retry cannot add people twice. Part of Campaigns.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
limitintegersìHow many more people at most. (1–10000000)
idempotency_keystringnoIntestazione Idempotency-Key (max 200 caratteri). Riutilizzala solo per ritentare esattamente questa richiesta. (max 200 caratteri)
Returns{added, broadcast}.
Esempio di params per tools/call
{
  "name": "send_broadcast_to_more",
  "arguments": {
    "broadcast_id": "bc_123",
    "limit": 500,
    "idempotency_key": "october-update-more-1"
  }
}
Read-onlyget_broadcast_report
GET /broadcasts/:broadcast_id/report

Get a broadcast report

Campaigns: Engagement for a sending or sent broadcast: unique and total opens and clicks, bounces, complaints, and unsubscribes with rates in percent, the same per inbox provider, clicks per link, first opens and clicks by hour, and the average of the previous five broadcasts. Opens are estimates: automated requests (scanners, link previews, privacy prefetching) are counted only in machine. Never claim that a person read the email. Fails with 409 for a draft.

ParametroTipoObbligatorioDescrizione
broadcast_idstringsìBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Returns{stats: {sent, delivered, opened, clicked, bounced, complained, unsubscribed, opens, clicks, rates}, providers, links, timeline, average, machine, tracking, totals, remaining}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_broadcast_report",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}
Read-onlyget_newsletter_settings
GET /newsletter-settings

Get newsletter settings

Campaigns: The postal address added to every marketing email footer, the design (accent color, font, alignment) used for Markdown and block content, list cleanup settings, and default test recipients.

Nessun parametro.

Returns{postalAddress, design: {accentColor, font, align}, cleanup: {enabled, afterSends, quietDays, subject, body, from}, testRecipients}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_newsletter_settings",
  "arguments": {}
}
Changes stateupdate_newsletter_settings
PATCH /newsletter-settings

Update newsletter settings

Campaigns: Change the postal address (required in marketing email by CAN-SPAM and CASL), design, list cleanup, or default test recipients. Omitted keys keep their value. List cleanup is on by default and sends email automatically: a subscriber who got afterSends broadcasts in a row without opening or clicking and has been quiet for quietDays gets one "still want these?" email; a week later those who did not confirm become dormant (kept, but skipped by broadcasts). Confirm with the user before turning it on or changing its email.

ParametroTipoObbligatorioDescrizione
postal_addressstringnoSender's postal address for the footer. Empty string removes it. (max 300 chars)
designobjectnoRendering design for Markdown and block content.
design.accentColorstring,nullnoHex color like #0a7d4f, or null for the default.
design.fontstringnoFont family. (one of sans, serif, mono)
design.alignstringnoText alignment. (one of left, center)
cleanupobjectnoList cleanup of readers who stopped opening.
cleanup.enabledbooleannoTurn list cleanup on or off.
cleanup.afterSendsintegernoBroadcasts in a row without an open or click (3-50). (3–50)
cleanup.quietDaysintegernoDays without engagement (30-730). (30–730)
cleanup.subjectstring,nullnoSubject of the cleanup email; merge tags allowed. (max 200 chars)
cleanup.bodystring,nullnoBody text of the cleanup email. (max 2000 chars)
cleanup.fromstring,nullnoSender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars)
test_recipientsstring[]noDefault addresses for send_broadcast_test (up to 5). (0–5 items)
ReturnsThe updated settings.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_newsletter_settings",
  "arguments": {
    "postal_address": "Acme Inc., 1 Main St, Springfield",
    "design": {
      "accentColor": "#0a7d4f"
    }
  }
}
Read-onlyget_campaign_overview
GET /campaigns/overview

Get campaign overview

Campaigns: Subscriber growth and recent results for the last days (7-365, default 30): active, dormant, and pending subscribers, joined and left, a daily series, and the six latest broadcasts with open and click rates (bot-filtered estimates) and their average.

ParametroTipoObbligatorioDescrizione
daysintegernoWindow in days, 7 to 365. Defaults to 30. (7–365)
Returns{subscribers: {active, dormant, pending, joined, left}, series: [{day, subscribers, joined, left}], recent: [{id, name, subject, status, startedAt, sent, openRate, clickRate}], averages}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_campaign_overview",
  "arguments": {
    "days": 30
  }
}
Read-onlylist_uploaded_images
GET /uploads/images

List uploaded images

Campaigns: The workspace's 60 most recent editor image uploads with their public URLs (https://sendhq.cc/i/<id>), to reuse in broadcast HTML, Markdown, or image blocks. Uploading needs the dashboard or the REST API (raw image body). Paginated.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{id, url, width, height, size, filename, createdAt}], pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_uploaded_images",
  "arguments": {}
}

Automations, events, and sending limits

Sends real emailtrack_event
POST /events

Record something a contact did

SENDS REAL EMAIL later, when an automation is listening: the contact enters every automation that is on and starts on this event, and that automation then emails them on its schedule, within the workspace's sending limits and hours. Only record what the person really did. In order: the contact changes in contact and the event are saved; open enrolments whose automation names the event as its goal end as converted, and ones that list it as a stop event end; then the contact enters the automations that start on it, unless already in them or reentry forbids it. A contact that is unsubscribed, bounced, or complained is recorded and can leave automations but never enters one. A new contact needs contact.consent_basis. Pass dedupe_key so a retry changes nothing and returns the first result. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
emailstringsìThe contact's email address. (max 320 chars)
eventstringsìWhat they did: a lowercase letter, then a-z, 0-9, and _ (e.g. checkout_started). Names starting email. are reserved. (max 64 chars)
propertiesobjectnoUp to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved.
occurred_atstringnoWhen it happened, ISO 8601 with a time zone. Defaults to now; may not be in the future. The automation's emails are timed from it. (max 40 chars)
dedupe_keystringnoStable ID for this event (max 200 chars). A second call with the same key records nothing and returns the first result. (max 200 chars)
contactobjectnoChanges to the contact, applied with the event.
contact.namestringnoDisplay name. (max 200 chars)
contact.fieldsobjectnoCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
contact.timezonestringnoIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
contact.localestringnoLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
contact.consent_basisstringnoHow this person agreed to receive your email, e.g. Created an account on acme.com and accepted product emails. Required when the email is not a contact yet. 10-500 characters. (max 500 chars)
Returns{id, contact_id, started: [automation keys the contact entered], ended: [automation keys the contact left]}.
Esempio di params per tools/call
{
  "name": "track_event",
  "arguments": {
    "email": "ada@example.net",
    "event": "checkout_started",
    "properties": {
      "plan": "pro"
    },
    "dedupe_key": "checkout_8f3a"
  }
}
Read-onlylist_automations
GET /automations

List automations

Automations: Every automation in priority order with its status (draft, on, or off), how many emails it has, and totals for the last 30 days (entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held). held counts each time an email was made to wait by the sending limits, the sending hours, or the automation's daily cap. Each automation carries domain, the domain of its from_address (null while it has no sender). domain narrows the list to the automations that send from one domain (none: those with no sender yet); domains always lists every sender domain of the workspace, in alphabetical order, with how many automations each has. Email bodies are not included; use get_automation. For other date ranges and daily numbers use get_automation_report. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
domainstringnoOnly the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{id, key, name, domain, audience_label, goal_label, status, entry, exit_rules, position, settings, from_name, from_address, reply_to, switched_on_at, created_at, updated_at} plus steps_count and totals], count, domains: [{domain, count}], pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_automations",
  "arguments": {
    "domain": "example.com"
  }
}
Read-onlyget_automation
GET /automations/:automation_key

Get an automation

Automations: One automation with its emails in order and their language versions, how many people are in it now, and overlap: the other automations that are on and currently have the same people in them, with goes_first true for one that ranks above this automation (the shared people get its emails first and wait in this one). to_fill lists what must still be filled in before it can be turned on: placeholders of the template library left in its emails, and workspace names they print that are blank. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
ReturnsThe automation (with domain, the domain of its from_address, or null) with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, overlap [{key, name, contacts, position, goes_first}], merge_fields [{key, label}]: the merge tags its emails print, in plain words, and to_fill [{id, position, locale, where, placeholder, key, message}].
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Changes statecreate_automation
POST /automations

Create an automation

Automations: Create a timed sequence of emails for one kind of person, as a draft. To start from a ready-made email instead (welcome, onboarding, trial, abandoned checkout, failed payment, winback and more), use use_automation_template. Nothing is sent until set_automation_status turns it on. key is its address and cannot be changed. entry says how people enter, exit_rules when they leave, and steps are the emails, each due offset_seconds after the person entered. from_address must be on a verified domain. Fails with 409 when the key is taken. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
keystringsìAddress of the automation: 1-63 characters of a-z, 0-9, and - (e.g. checkout-recovery). (max 63 chars)
namestringsìName shown in the dashboard. (max 200 chars)
audience_labelstringnoWho this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstringnoWhat converting means, in a word or two, e.g. paid. (max 80 chars)
entryobjectnoHow people enter. {type: "event", event} starts on an event recorded with track_event; {type: "manual"} only through enroll_contact. bucket (with segment_id) and date_field (with field) are stored, but nobody enters through them automatically yet. reentry: never (default) or after_end.
entry.typestringsìEntry type. (one of event, bucket, date_field, manual)
entry.eventstringnoEvent name for an event entry, e.g. checkout_started.
entry.segment_idstringnoSegment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstringnoContact field key for a date_field entry. (max 40 chars)
entry.reentrystringnoWhether someone who finished may enter again. (one of never, after_end)
exit_rulesobjectnoWhen people leave. goal_event ends the enrolment as converted and credits the latest email sent within attribution_days before it. Each of stop_events ends it without a conversion. An automation with no goal must say so with no_goal: true. Sent whole: it replaces the current rules.
exit_rules.goal_eventstring,nullnoEvent that counts as converting, e.g. payment_completed.
exit_rules.no_goalbooleannoTrue when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]noEvents that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysintegernoDays before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobjectnoPer-automation settings. Omitted keys keep their value.
settings.exempt_from_holdbooleannoSkip the workspace's per-person limits (max_emails and min_gap_hours) for this automation. The sending hours still apply, and its emails still count toward the limits of other automations.
settings.daily_send_capinteger,nullnoAt most this many emails a day from this automation, counted by the day of the workspace's default_timezone; emails over it wait until the next day. null for no cap. (1–…)
settings.daily_entry_capinteger,nullnoStored for bucket entries, which are not started automatically yet. It does not limit people entering by event or through enroll_contact. null for no cap. (1–…)
settings.holdout_pctnumbernoPercent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysintegernoAn email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysintegernoHow long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positionintegernoPriority. While one person is in several automations that are on, only the one with the lowest position emails them; the others wait and resume resume_after_days after it ends. (0–100000)
from_namestringnoSender display name, e.g. Acme. (max 120 chars)
from_addressstringnoSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringnoReply-To address. (max 320 chars)
stepsobject[]noThe emails, in order. position defaults to the place in this list. (0–50 items)
steps[].positionintegernoPosition of the email in the automation, 1 to 50. (1–50)
steps[].subjectstringnoSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
steps[].preheaderstringnoInbox preview line. (max 300 chars)
steps[].contentobjectnoBlock document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
steps[].htmlstringnoHTML body. The unsubscribe footer is added automatically.
steps[].textstringnoCorpo in testo semplice.
steps[].editorstringnoHow the email is made: blocks (the dashboard's writing editor, the default), html (your own HTML) or design (the dashboard's drag-and-drop builder). Only the builder makes a design; to send a designed email yourself, send html with editor html. (one of blocks, html, design)
steps[].offset_secondsintegernoWhen the email is due, in seconds after the moment the person entered (3600 = one hour, 86400 = one day). May be negative for emails that lead up to a date. When several emails are due at once, only the latest is sent and the earlier ones are skipped. (-31622400–31622400)
steps[].skip_if_emptystring[]noMerge keys, e.g. ["fields.plan"]. The email is skipped for a contact where any of them is blank, 0, or false. (0–20 items)
steps[].ignore_send_windowbooleannoSend as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply.
ReturnsThe automation with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, and overlap [{key, name, contacts}].
Esempio di params per tools/call
{
  "name": "create_automation",
  "arguments": {
    "key": "checkout-recovery",
    "name": "Checkout recovery",
    "audience_label": "Started checkout and left",
    "goal_label": "paid",
    "from_name": "Acme",
    "from_address": "hello@example.com",
    "entry": {
      "type": "event",
      "event": "checkout_started"
    },
    "exit_rules": {
      "goal_event": "payment_completed"
    },
    "steps": [
      {
        "offset_seconds": 3600,
        "subject": "Still thinking it over, {{ first_name | there }}?",
        "html": "<p>Your cart is waiting.</p>"
      }
    ]
  }
}
Changes stateupdate_automation
PATCH /automations/:automation_key

Edit an automation

Automations: Change an automation's name, labels, entry, exit rules, sender, or priority. settings are merged; entry and exit_rules replace the current ones. The key and the status cannot be changed here (use set_automation_status), and emails are changed with set_automation_step. If the automation is on, the change applies to people in it now, and an edit that would leave it unable to send is refused with 422 automation_not_ready. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
namestringnoName shown in the dashboard. (max 200 chars)
audience_labelstringnoWho this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstringnoWhat converting means, in a word or two, e.g. paid. (max 80 chars)
entryobjectnoHow people enter. {type: "event", event} starts on an event recorded with track_event; {type: "manual"} only through enroll_contact. bucket (with segment_id) and date_field (with field) are stored, but nobody enters through them automatically yet. reentry: never (default) or after_end.
entry.typestringsìEntry type. (one of event, bucket, date_field, manual)
entry.eventstringnoEvent name for an event entry, e.g. checkout_started.
entry.segment_idstringnoSegment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstringnoContact field key for a date_field entry. (max 40 chars)
entry.reentrystringnoWhether someone who finished may enter again. (one of never, after_end)
exit_rulesobjectnoWhen people leave. goal_event ends the enrolment as converted and credits the latest email sent within attribution_days before it. Each of stop_events ends it without a conversion. An automation with no goal must say so with no_goal: true. Sent whole: it replaces the current rules.
exit_rules.goal_eventstring,nullnoEvent that counts as converting, e.g. payment_completed.
exit_rules.no_goalbooleannoTrue when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]noEvents that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysintegernoDays before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobjectnoPer-automation settings. Omitted keys keep their value.
settings.exempt_from_holdbooleannoSkip the workspace's per-person limits (max_emails and min_gap_hours) for this automation. The sending hours still apply, and its emails still count toward the limits of other automations.
settings.daily_send_capinteger,nullnoAt most this many emails a day from this automation, counted by the day of the workspace's default_timezone; emails over it wait until the next day. null for no cap. (1–…)
settings.daily_entry_capinteger,nullnoStored for bucket entries, which are not started automatically yet. It does not limit people entering by event or through enroll_contact. null for no cap. (1–…)
settings.holdout_pctnumbernoPercent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysintegernoAn email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysintegernoHow long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positionintegernoPriority. While one person is in several automations that are on, only the one with the lowest position emails them; the others wait and resume resume_after_days after it ends. (0–100000)
from_namestringnoSender display name, e.g. Acme. (max 120 chars)
from_addressstringnoSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringnoReply-To address. (max 320 chars)
ReturnsThe automation with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), enrollments {active, waiting}, and overlap [{key, name, contacts}].
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_automation",
  "arguments": {
    "automation_key": "checkout-recovery",
    "name": "Checkout recovery",
    "settings": {
      "holdout_pct": 10
    }
  }
}
Destructivedelete_automation
DELETE /automations/:automation_key

Delete an automation

DESTRUCTIVE: permanently delete an automation with its emails, language versions, enrolments, send records, and statistics. Only a draft or switched-off automation that nobody is currently in can be deleted; otherwise it fails with 409. Confirm with the user first. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Changes stateset_automation_step
PUT /automations/:automation_key/steps/:position

Create or change an email of an automation

Automations: Create the email at position, or change the fields you pass on the one that is there; fields left out keep their value. If the automation is on, people who have not received this email yet get the new version, so confirm the wording with the user. An existing email keeps its ID: people who already received it are not sent it again. With template, the email becomes that template of the library (see list_automation_templates): its subject, preview text and content replace the email's and its language versions are removed. While the automation is on, an email must keep a subject and content, and may not hold a placeholder of the template library such as [First step] or print a workspace name that is blank (422 automation_not_ready with problems). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegersìPosition of the email in the automation, 1 to 50. (1–50)
templatestringnoId of a template of the library, e.g. welcome-note (not a set). The email becomes that template; other fields passed here are applied on top. The email's wait is not the template's: pass offset_seconds. (max 63 chars)
subjectstringnoSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringnoInbox preview line. (max 300 chars)
contentobjectnoBlock document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
htmlstringnoHTML body. The unsubscribe footer is added automatically.
textstringnoCorpo in testo semplice.
editorstringnoHow the email is made: blocks (the dashboard's writing editor, the default), html (your own HTML) or design (the dashboard's drag-and-drop builder). Only the builder makes a design; to send a designed email yourself, send html with editor html. (one of blocks, html, design)
offset_secondsintegernoWhen the email is due, in seconds after the moment the person entered (3600 = one hour, 86400 = one day). May be negative for emails that lead up to a date. When several emails are due at once, only the latest is sent and the earlier ones are skipped. (-31622400–31622400)
skip_if_emptystring[]noMerge keys, e.g. ["fields.plan"]. The email is skipped for a contact where any of them is blank, 0, or false. (0–20 items)
ignore_send_windowbooleannoSend as soon as it is due, outside the workspace's sending hours too. The per-person limits still apply.
ReturnsThe email: {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "set_automation_step",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 2,
    "offset_seconds": 86400,
    "subject": "Your cart is still here",
    "html": "<p>Pick up where you left off.</p>"
  }
}
Destructivedelete_automation_step
DELETE /automations/:automation_key/steps/:position

Remove an email from an automation

DESTRUCTIVE: remove the email at position from an automation. It is no longer sent or listed; records of who already received it are kept. While the automation is on, its only email cannot be removed (409). Confirm with the user first. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegersìPosition of the email in the automation, 1 to 50. (1–50)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_automation_step",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 3
  }
}
Changes stateset_automation_step_variant
PUT /automations/:automation_key/steps/:position/variants/:locale

Create or change a language version of an email

Automations: Save the version of one email for contacts whose locale is this language tag (e.g. fr); a contact with a regional locale such as pt-br gets the pt version when there is no pt-br one. Fields left out keep their value. A version without a body uses the email's own body, and a blank subject or preheader falls back to the email's. Contacts without a matching version get the email as written. If the automation is on, matching contacts who have not received this email yet get this version. While the automation is on, a version may not hold a placeholder of the template library or print a workspace name that is blank (422 automation_not_ready). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegersìPosition of the email in the automation, 1 to 50. (1–50)
localestringsìLanguage tag of the version, e.g. fr or pt-br. (max 35 chars)
subjectstringnoSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringnoInbox preview line. (max 300 chars)
contentobjectnoBlock document ({type: "doc", content: [...]}), as the dashboard editor stores it. Sent without html, it is rendered with the workspace design. On an email built in the dashboard's drag-and-drop builder (editor design) it is the builder's project instead: opaque, never write one by hand, and send it back only unchanged together with its html.
htmlstringnoHTML body. The unsubscribe footer is added automatically.
textstringnoCorpo in testo semplice.
Returns{locale, subject, preheader, content, html, text, updated_at}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "set_automation_step_variant",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 1,
    "locale": "fr",
    "subject": "Vous hésitez encore ?",
    "html": "<p>Votre panier vous attend.</p>"
  }
}
Sends real emailset_automation_status
POST /automations/:automation_key/status

Turn an automation on or off

SENDS REAL EMAIL when status is on: from then on, everyone who enters the automation is emailed on its schedule, within the workspace's sending limits and hours (get_sending_limits), and people already in it continue. Use preview_automation to see who would get which email. Only turn it on when the user asked for this automation to start. Turning on checks an entry, a goal or exit_rules.no_goal, at least one email with a subject and content, no placeholder of the template library such as [First step] or [Link to plans] left in any email (subject, preview text, body, or a link's address), and no blank workspace name that an email prints (422 automation_not_ready with problems, which names each email and detail; get_automation lists the same under to_fill), a sender on a verified domain (403), and an active subscription (402). off stops new entries and sending; people in it stay and continue if it is turned on again, except that an email more than stale_days overdue by then is skipped. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
statusstringsìon to start sending, off to stop. (one of on, off)
ReturnsThe automation: {id, key, name, domain, audience_label, goal_label, status, entry, exit_rules, position, settings, from_name, from_address, reply_to, switched_on_at, created_at, updated_at}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "set_automation_status",
  "arguments": {
    "automation_key": "checkout-recovery",
    "status": "off"
  }
}
Sends real emailsend_automation_test_email
POST /automations/:automation_key/steps/:position/test

Send one automation email to yourself as a test

SENDS REAL EMAIL: one email of an automation, marked [Test], to the account's own address (get_account -> user.email) and nowhere else; a recipient cannot be given. It is the email as the automation would send it (the language version for locale, the same sender, unsubscribe footer and checks), with stand-in values for its merge tags; sample replaces any of them. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's per-person sending limits, it is not tracked, and the automation does not have to be on. It counts toward the workspace's own sending allowance. With dry_run: true nothing is sent and the result is the email as the test would deliver it, with locales and the sample values used. Fails with 422 automation_not_ready when the automation has no sender or the email has no subject or content, and 429 test_limit_reached after 100 test emails in 24 hours. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegersìPosition of the email in the automation, 1 to 50. (1–50)
localestringnoSend the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars)
sampleobjectnoValues to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set.
dry_runbooleannoSend nothing; return the email as the test would deliver it.
Returns{to, position, locale, subject, id: em_…, status: sent|held}. With dry_run: {dry_run: true, to, from, position, locale, locales, subject, preheader, html, text, sample: [{key, label, value}]}.
Esempio di params per tools/call
{
  "name": "send_automation_test_email",
  "arguments": {
    "automation_key": "checkout-recovery",
    "position": 1
  }
}
Sends real emailsend_automation_test
POST /automations/:automation_key/test

Send every email of an automation to yourself as tests

SENDS REAL EMAIL: every email of an automation, in order, marked [Test 1 of 3], [Test 2 of 3] and so on, to the account's own address (get_account -> user.email) and nowhere else, without waiting for the emails' delays. Rendering, footer, checks and stand-in values are as in send_automation_test_email. A test is not part of the automation: nobody is enrolled, it is in no report, it counts toward nobody's per-person sending limits, it is not tracked, and the automation does not have to be on. It counts toward the workspace's own sending allowance. Nothing is sent unless everything can be: a sender, a subject and content on every email (422 automation_not_ready with problems), and room for all of them under 100 test emails in 24 hours (429 test_limit_reached). If a send is refused after others went out, the rest are not tried and each email's outcome is returned. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
localestringnoSend the language version a contact with this language would get (such as fr or pt-br). Omit for the email as written. (max 35 chars)
sampleobjectnoValues to print for merge tags, by key, in place of the stand-ins (first_name is Alex, and so on). email, product_name, and sender_name cannot be set.
Returns{to, data: [{position, locale, subject, id: em_…, status: sent|held|failed, error?}], count, sent, failed, not_sent}.
Esempio di params per tools/call
{
  "name": "send_automation_test",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Sends real emailenroll_contact
POST /automations/:automation_key/enroll

Add a contact to an automation

SENDS REAL EMAIL on the automation's schedule: starts the automation for one existing, subscribed contact, counting from anchor_at (now by default). Only call it when the user asked for this person to get this sequence. The automation must be on (409 automation_not_on). Fails with 404 when the email is not a contact (add it with upsert_contact), 422 when the contact cannot be mailed, and 409 when the contact is already in it or went through it before and re-entry is not allowed. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringsìEmail address of an existing contact. (max 320 chars)
propertiesobjectnoUp to 50 values (string, number, or boolean; strings are cut at 500 characters), e.g. {"plan": "pro"}. Usable in the automation's emails as merge tags such as {{ plan }}. The names email, name, first_name, last_name, and fields are reserved.
anchor_atstringnoThe moment the emails' offsets count from, ISO 8601 with a time zone. Defaults to now; may lie ahead for emails that lead up to a date. (max 40 chars)
ReturnsThe enrolment: {id, automation_key, contact_id, status, source, is_holdout, anchor_at, entered_at, next_due_at, exit_reason, ended_at, converted_at}.
Esempio di params per tools/call
{
  "name": "enroll_contact",
  "arguments": {
    "automation_key": "checkout-recovery",
    "email": "ada@example.net",
    "properties": {
      "plan": "pro"
    }
  }
}
Changes stateexit_contact
POST /automations/:automation_key/exit

Take a contact out of an automation

Automations: End a contact's open enrolment in one automation, so no further emails of it are sent to them. Other automations and broadcasts are not affected, and the contact stays subscribed. Fails with 404 when the contact is not in it. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringsìEmail address of the contact. (max 320 chars)
reasonstringnoWhy, for the record (max 200 chars). Defaults to manual. (max 200 chars)
ReturnsThe ended enrolment: {id, automation_key, contact_id, status, source, is_holdout, anchor_at, entered_at, next_due_at, exit_reason, ended_at, converted_at}.
Esempio di params per tools/call
{
  "name": "exit_contact",
  "arguments": {
    "automation_key": "checkout-recovery",
    "email": "ada@example.net",
    "reason": "Asked support to stop"
  }
}
Read-onlypreview_automation
GET /automations/:automation_key/preview

Preview what an automation would send now

Automations: A dry run. For the people in the automation now, in the order they come due, what would happen if each were evaluated at this moment. outcome is send (the email in step would go out), scheduled (nothing is due before until), held (the email waits until until; reason is limit_cap, limit_gap, window, or daily_cap), waiting (behind the higher-priority automation in behind), skip (reason is stale, empty_field, or holdout), exit (the contact can no longer be mailed and would leave), complete, blocked (automation_off or subscription_required), or in_progress. Read-only: nothing is sent or changed. Use it before set_automation_status, or after changing limits, to see who gets which email. It applies the automation's own rules and does not foresee a refusal only a real send meets, such as the workspace's daily sending limit or a paused sender. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{automation_key, status, evaluated_at, data: [{enrollment_id, contact_id, email, status, next_due_at, outcome, reason, until, step: {position, subject, locale}, behind: {key, name}, superseded}], count, counts, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "preview_automation",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Read-onlyget_automations_overview
GET /automations/overview

Get results across all automations

Automations: What every automation of the workspace did in a date range (the last 30 days by default, at most 366 days): totals and one entry per day for people who entered, emails sent, delivered, opened, clicked, and converted (a goal event credited to an email), plus bounces, complaints, unsubscribes, and held (emails made to wait by a limit). Days on which nothing happened are in the series with zeros. domain narrows it to the automations that send from one domain (none: those with no sender yet). Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
fromstringnoFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringnoLast day of the report as a UTC date (YYYY-MM-DD), inclusive.
domainstringnoOnly the automations that send from this domain: the exact domain of their from_address (e.g. example.com), or none for automations with no sender yet. (max 253 chars)
Returns{from, to, totals: {entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}, series: [{day, entered, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}]}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_automations_overview",
  "arguments": {
    "from": "2026-10-20",
    "to": "2026-11-18"
  }
}
Read-onlyget_automation_report
GET /automations/:automation_key/report

Get the results of one automation

Automations: The results of one automation in a date range (the last 30 days by default, at most 366 days): the same totals and daily series as get_automations_overview, and steps, one row per email with what it sent and what came of it. An email that was removed is listed with archived: true while it still has numbers in the range. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
fromstringnoFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringnoLast day of the report as a UTC date (YYYY-MM-DD), inclusive.
Returns{automation: {key, name, status, goal_label}, from, to, totals, series: [{day, ...}], steps: [{step_id, position, subject, offset_seconds, archived, sent, delivered, opened, clicked, converted, bounced, complained, unsubscribed, held}]}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_automation_report",
  "arguments": {
    "automation_key": "checkout-recovery"
  }
}
Read-onlylist_automation_people
GET /automations/:automation_key/people

List the people in an automation

Automations: One row per person who did did in an automation, most recent first: entered (the default: everyone who was ever in it), sent, delivered, opened, clicked, converted (their goal was credited to an email), bounced, unsubscribed, or waiting (waiting now behind a higher-priority automation). step narrows every filter except entered and waiting to one email. Each row has the contact's email and name, when they did it, their enrolment's status, and latest: the most recent thing that happened to them in the automation. counts says how many people each filter would list. Read one person's full history with get_automation_person. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
didstringnoWhat the people did. Defaults to entered. (one of entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, waiting)
stepintegernoOnly this email of the automation, by its position. (1–50)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{automation_key, did, step, data: [{contact_id, email, name, contact_status, enrollment_id, enrollment_status, at, latest: {did, at, step_position, reason}}], count, next_cursor, counts, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_automation_people",
  "arguments": {
    "automation_key": "checkout-recovery",
    "did": "clicked"
  }
}
Read-onlyget_automation_person
GET /automations/:automation_key/people/:contact_id

Get one person's history in an automation

Automations: Everything that happened to one contact in an automation: each enrolment and how it ended, each email with when it was sent, delivered, first opened, first clicked, bounced, complained about, or unsubscribed from, every open and click on it (machine: true marks an automated request, which is not counted), and the conversion with the email it was credited to. Fails with 404 for a contact that was never in the automation. Opens and clicks are estimates: each email counts once, at its first open or click by a person, and automated requests (scanners, link previews, privacy prefetching) are never counted. Never claim that a person read an email. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
automation_keystringsìAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
contact_idstringsìContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Returns{automation_key, contact: {id, email, name, status}, enrollments: [{id, status, source, is_holdout, anchor_at, entered_at, next_due_at, last_sent_at, exit_reason, ended_at, converted_at, converted_send_id}], sends: [{id, enrollment_id, step_id, step_position, subject, status, skip_reason, locale, email_id, sent_at, delivered_at, opened_at, clicked_at, bounced_at, complained_at, unsubscribed_at, converted_at, open_count, machine_open_count, click_count, events: [{kind, machine, reason, position, url, country, at}]}], conversion: {enrollment_id, converted_at, goal_event, send_id, step_position}}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_automation_person",
  "arguments": {
    "automation_key": "checkout-recovery",
    "contact_id": "ct_123"
  }
}
Read-onlyget_sending_limits
GET /automation-settings

Get automation sending limits

Automations: How much automation email one person may get across every automation, and when: at most max_emails in any period_days, at least min_gap_hours apart, only between window_start and window_end (hours in the contact's time zone, or default_timezone) on weekdays (0 = Sunday to 6 = Saturday). An email that would break a limit is not dropped: it waits until the limits allow it. Also product_name and sender_name, available to every automation email as merge tags. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

Nessun parametro.

Returns{max_emails, period_days, min_gap_hours, window_start, window_end, weekdays, default_timezone, product_name, sender_name, updated_at}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_sending_limits",
  "arguments": {}
}
Changes stateupdate_sending_limits
PUT /automation-settings

Update automation sending limits

Automations: Change the workspace's per-person limits and sending hours for automation email. Omitted keys keep their value. Looser limits mean people can get more email, sooner: confirm with the user before raising max_emails, shortening min_gap_hours, or widening the hours. product_name and sender_name are the names the emails of the template library print; one that an automation that is on prints cannot be cleared (409 workspace_name_in_use). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
max_emailsintegernoMost automation emails one person may get in period_days. Default 2. (1–50)
period_daysintegernoThe period max_emails applies to, in days. Default 7. (1–90)
min_gap_hoursintegernoLeast time between two automation emails to one person, in hours. Default 44. (0–720)
window_startintegernoFirst hour of the day emails may go out, local time (0-23). Default 9. (0–23)
window_endintegernoHour sending stops, local time (1-24); must be later than window_start. Default 18. (1–24)
weekdaysinteger[]noDays emails may go out: 0 = Sunday to 6 = Saturday. Default [1, 2, 3, 4, 5]. (1–7 items)
default_timezonestringnoIANA time zone used for contacts that have none, e.g. Europe/London. (max 64 chars)
product_namestringnoYour product's name, for {{ product_name }}. (max 120 chars)
sender_namestringnoWho the emails are from, for {{ sender_name }}. (max 120 chars)
ReturnsThe updated limits.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_sending_limits",
  "arguments": {
    "max_emails": 3,
    "min_gap_hours": 24,
    "default_timezone": "Europe/London"
  }
}
Read-onlylist_automation_templates
GET /automation-library

List automation templates

Automations: The template library: ready-made lifecycle emails to start an automation from instead of writing one. It covers welcome, onboarding tips, a nudge to finish setup (activation), trial ending and trial ended, abandoned checkout, failed payment (dunning), receipt, upgrade at a usage limit, feature announcement, review request, feedback score (NPS), cancellation survey, and winback for retention. Each template has a name, a one-line purpose, the goal it serves (group), its subject, the merge tags it prints, and start: the suggested entry event, the email's wait, and the goal event that ends the automation for a person. sets are templates that arrive together as one automation: three onboarding tips, trial ending then trial ended, and payment failed then a last notice. fill_in lists what only the user knows: placeholders in square brackets such as [First step] or [Link to plans], and the workspace names the email prints. Email bodies are not included; use get_automation_template. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{version, groups, data: [{id, kind, name, purpose, group, set, subject, preview_text, needs_consent, start: {entry, offset_seconds, goal_event, goal_label, skip_if_empty}, merge_keys, fill_in: [{kind, key, placeholder, label, example}]}], sets: [{id, kind, name, purpose, group, needs_consent, emails: [{template, offset_seconds}], start, merge_keys, fill_in}], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_automation_templates",
  "arguments": {}
}
Read-onlyget_automation_template
GET /automation-library/:template_id

Get an automation template

Automations: One template or one set of the template library, as the draft automation it would make: the suggested start and goal, what the user must fill in, and every email in order with its wait, subject, the email as a block document (content), and preview: the subject and text as this workspace would send them, with sample values for the merge tags. Read it to show the user a welcome, onboarding, trial, abandoned checkout, failed payment (dunning), upgrade, cancellation or winback email before using it. Placeholders such as [First step] are shown as written; a workspace name that is not set reads "Your product" or "Your name" in the preview. Then use_automation_template makes the draft, or set_automation_step with template loads one email into an existing automation. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
template_idstringsìId of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars)
Returns{id, kind (email or set), name, purpose, group, set, needs_consent, start: {entry, goal_event, goal_label}, merge_keys, fill_in: [{kind, key, placeholder, label, example}], emails: [{template, name, offset_seconds, skip_if_empty, subject, preview_text, content, preview: {subject, preheader, text, html}}]}. preview.html is null.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_automation_template",
  "arguments": {
    "template_id": "welcome-note"
  }
}
Changes stateuse_automation_template
POST /automation-library/:template_id/use

Create an automation from a template

Automations: Create a draft automation from a template or a set of the library, ready-made: a welcome email, three onboarding tips, a nudge to finish setup, trial ending and trial ended, abandoned checkout, failed payment (dunning) notices, a receipt, an upgrade email at a usage limit, a feature announcement, a review request, a feedback score, a cancellation survey, or a winback for retention. The draft has the emails, the suggested entry event and the suggested goal. Nothing is sent: it stays a draft until set_automation_status turns it on, and that is refused while anything in to_fill is left. to_fill lists each placeholder to replace, by email (ask the user for the real words and links, then use set_automation_step), and each workspace name the emails print that is blank (product_name, sender_name: set with update_sending_limits). Make sure the entry event is one the workspace records (list_event_names); change the start with update_automation. from_address must be on a verified domain. Fails with 404 for an unknown template and 409 when key is taken. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
template_idstringsìId of a template or a set, as returned by list_automation_templates (e.g. welcome-note, checkout-not-finished, payment-failed-notices). (max 63 chars)
keystringnoAddress of the new automation: 1-63 characters of a-z, 0-9, and -. Defaults to the template's id, with a number added when that is taken. (max 63 chars)
namestringnoName shown in the dashboard. Defaults to the template's own name. (max 200 chars)
from_namestringnoSender display name, e.g. Acme. (max 120 chars)
from_addressstringnoSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringnoReply-To address. (max 320 chars)
ReturnsThe new automation (status draft) with steps (each {id, position, offset_seconds, subject, preheader, editor, content, html, text, skip_if_empty, ignore_send_window, variants}), merge_fields [{key, label}], template, and to_fill [{id, position, locale, where, placeholder, key, message}]: what must be filled in before it can be turned on.
Esempio di params per tools/call
{
  "name": "use_automation_template",
  "arguments": {
    "template_id": "welcome-note",
    "name": "Welcome",
    "from_name": "Dana from Acme",
    "from_address": "dana@example.com"
  }
}
Read-onlylist_events
GET /events

List what contacts did

Automations: The events recorded for the workspace, newest first: who (the contact's id, email, and name), what they did (the event name, and the same as words), when, its properties, where it came from (source.type: api for the workspace's own code, connection with the connection's name, upload for a spreadsheet, system for SendHQ itself), and effects: the automations it started, ended, or converted for that contact. Filter by contact (a contact ID or an email address), name (one event name), and from / to. With contact, the result also lists every automation that contact is or was in (enrollments). An event being recorded does not mean an email was sent: check the automation with list_automation_people. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
contactstringnoOnly this contact: a contact ID or an email address. (max 320 chars)
namestringnoOnly this event, e.g. checkout_started. See list_event_names. (max 64 chars)
fromstringnoEvents from this UTC date (YYYY-MM-DD) or ISO 8601 date-time on. (max 40 chars)
tostringnoEvents up to this UTC date (the whole day) or ISO 8601 date-time. (max 40 chars)
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{id, contact: {id, email, name}, event, words, occurred_at, received_at, source: {type, label, connection_id}, properties, effects: [{did, automation_key, automation_name}]}], count, next_cursor, enrollments (with contact), pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_events",
  "arguments": {
    "name": "checkout_started",
    "from": "2026-11-01"
  }
}
Read-onlylist_event_names
GET /events/names

List the kinds of event recorded

Automations: Every distinct event name recorded in the last 30 days with how many times, the most frequent first, each with the name as words (checkout_started reads checkout started). Use it to see what the workspace is being told about before creating an automation that starts on an event. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{event, words, count}], count, days, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_event_names",
  "arguments": {}
}
Read-onlylist_connections
GET /connections

List connections

Automations: The workspace's connections. A connection is a secret address another system posts to, such as a payment provider's webhook; what arrives is recorded as events, exactly as track_event records them. Each has its kind (stripe, dodo, or generic), whether it is enabled, whether a signing secret is set, the last four characters of its address, and last_delivery in plain words such as "Recorded 2 events" or "Refused: bad signature". The address and the signing secret are never returned here. Paginated. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Returns{data: [{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus last_delivery {id, at, result, reason, recorded, events, text, provider_event, email}], count, limit, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_connections",
  "arguments": {}
}
Read-onlyget_connection
GET /connections/:connection_id

Get a connection and its last deliveries

Automations: One connection with its last 50 deliveries, newest first: when each arrived, whether it was recorded, skipped, or refused and why (text says it in plain words), the sender's own event type, the names of the events recorded, and the contact's email address. Payloads are not stored. Use it to find out why something a provider sent did not show up. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
connection_idstringsìConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus last_delivery and deliveries: [{id, at, result, reason, recorded, events, text, provider_event, email}].
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}
Sends real emailcreate_connection
POST /connections

Create a connection

SENDS REAL EMAIL later, when an automation is listening: from the moment the address this returns is given to another system, everything that system posts is recorded as events without anyone looking, and a recorded event starts every automation that is on and starts on it. Only create one when the user asked to connect that system. Returns address once; it cannot be read again, so hand it to the user at once. kind is stripe or dodo (mapped for you: checkout_completed, checkout_abandoned, paid, payment_failed, subscription_started, subscription_renewed, subscription_cancelled, plan_changed) or generic with a mapping. consent_basis is recorded on every contact the connection creates. The provider's signing secret is set by a person in the dashboard or with the REST API, not here. A workspace may have 10 connections (409 connection_limit_reached). Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
namestringsìWhat to call it, e.g. Stripe. (max 80 chars)
kindstringsìstripe, dodo, or generic. (one of generic, stripe, dodo)
consent_basisstringsìHow the people this connection tells you about agreed to receive your email, e.g. Bought a plan on acme.com and accepted product emails. Recorded on every contact it creates. 10-500 characters. (max 500 chars)
event_prefixstringnoPut in front of every event name, e.g. stripe_. (max 32 chars)
enabledbooleannoDefaults to true. Pass false to create it switched off.
mappingobjectnoFor a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstringnoWhere the contact's email address is. (max 120 chars)
mapping.eventstringnoWhere the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestringnoOne fixed event name, instead of event. (max 64 chars)
mapping.timestringnoWhere the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstringnoWhere a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]noThe fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at} plus address (shown once) and last_delivery: null.
Esempio di params per tools/call
{
  "name": "create_connection",
  "arguments": {
    "name": "Stripe",
    "kind": "stripe",
    "consent_basis": "Bought a plan on acme.com and accepted product emails"
  }
}
Sends real emailupdate_connection
PATCH /connections/:connection_id

Change a connection or switch it on or off

SENDS REAL EMAIL later when enabled is set to true: what the connected system posts is recorded as events again, and a recorded event starts every automation that is on and starts on it. Only switch one on when the user asked. Also changes name, consent_basis, event_prefix, or a generic connection's mapping. While enabled is false the address answers 404 and records nothing. The kind cannot be changed. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
connection_idstringsìConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
namestringnoA new name. (max 80 chars)
enabledbooleannotrue: record what arrives. false: answer 404 and record nothing.
consent_basisstringnoHow the people this connection tells you about agreed to receive your email, e.g. Bought a plan on acme.com and accepted product emails. Recorded on every contact it creates. 10-500 characters. (max 500 chars)
event_prefixstringnoPut in front of every event name, e.g. stripe_. (max 32 chars)
mappingobjectnoFor a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstringnoWhere the contact's email address is. (max 120 chars)
mapping.eventstringnoWhere the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestringnoOne fixed event name, instead of event. (max 64 chars)
mapping.timestringnoWhere the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstringnoWhere a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]noThe fields to keep as event properties. Defaults to the top-level text, number, and boolean fields. (0–50 items)
Returns{id, name, kind, enabled, event_prefix, consent_basis, has_signing_secret, address_ending, mapping (generic only), created_at, updated_at}.
AnnotazioniidempotentHint
Esempio di params per tools/call
{
  "name": "update_connection",
  "arguments": {
    "connection_id": "acn_123",
    "enabled": false
  }
}
Destructivedelete_connection
DELETE /connections/:connection_id

Delete a connection

DESTRUCTIVE: permanently delete a connection with its delivery records. Its address stops working at once, so the system that posts to it starts getting 404 and nothing more is recorded from it. The events it already recorded stay. Confirm with the user first; to pause one instead, use update_connection with enabled: false. Automations are enabled workspace by workspace: a workspace that is not enabled gets 403 automations_not_enabled.

ParametroTipoObbligatorioDescrizione
connection_idstringsìConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
Restituisce{ok: true}.
AnnotazionidestructiveHint idempotentHint
Esempio di params per tools/call
{
  "name": "delete_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}

Account, utilizzo, analytics e chiavi

Sola letturaget_account
GET /account

Recupera account, utilizzo e fatturazione

Email del titolare dell'account, piano/livello di accesso, consegne per destinatario usate nel periodo corrente rispetto alla quota, domini usati rispetto al limite, trasferimento di allegati, riepilogo della reputazione, stato dell'abbonamento, piani pubblicati e conteggi del workspace. Usalo per controllare la quota residua o a chi può consegnare la prova (l'email dell'account).

Nessun parametro.

Restituisce{user: {email, …}, usage: {domainsUsed, domainLimit, recipientDeliveries, emailQuotaMonth, attachmentBytes, attachmentByteLimit, periodKey}, access: {tier, planCode}, reputation, infrastructure, billing: {status, subscriptions, …}, plans, workspace: {mailer, stats}}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_account",
  "arguments": {}
}
Read-onlyget_account_diagnostics
GET /account/diagnostics

Diagnose sending and receiving

One read that explains what is wrong with sending or receiving in this workspace: an issues list (unverified domains and missing DKIM records, inbound MX not ready, paused or throttled senders, quota or daily limit reached, trial restrictions, high bounce or complaint rates, failing webhooks), plan and usage against limits, each domain with its DKIM and inbound state, sending identities, 30-day deliverability and sender reputation, suppressions and unsubscribes, and the last 30 days of messages that were not sent (with reasons) plus bounce, complaint and reject events. Start here when a user asks why mail is not arriving. Never returns message bodies or secrets.

Nessun parametro.

Returns{generatedAt, windowDays, issues: [{severity, code, message}], plan: {tier, usage, sendingLimit}, domains: [{name, status, dkim: {required, verified, missing}, inbound}], sendingIdentities, inbound, deliverability: {sent, delivered, bounced, complained, rates, senders}, suppressions: {total, byReason, unsubscribes, recent}, failures: {notSent, recentNotSent, recentProviderEvents}, webhooks}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_account_diagnostics",
  "arguments": {}
}
Sola letturaget_analytics
GET /analytics

Recupera le analytics di invio

Analytics della dashboard per gli ultimi 7, 30 o 90 giorni: totali di inviate/ricevute/consegnate/bounce/bloccate/aperte/cliccate/segnalazioni di spam, una timeline giornaliera, i principali domini di invio e gli oggetti più frequenti.

ParametroTipoObbligatorioDescrizione
daysintegernoFinestra in giorni: 7, 30 (predefinito) o 90. (uno tra 7, 30, 90)
Restituisce{window, days, metrics, timeline: [{day, sent, received}], domains, topContent}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}
Sola letturalist_api_keys
GET /keys

Elenca i metadati delle chiavi API

Elenca nomi, prefissi non segreti e data dell'ultimo utilizzo delle chiavi API. Sola lettura: questo server MCP non può creare, ruotare o revocare chiavi; lo fa una persona nella dashboard. Paginato: il risultato include pagination {offset, limit, returned, total?, has_more, next_offset}.

ParametroTipoObbligatorioDescrizione
limitintegernoDimensione della pagina. Predefinita: 50. (predefinito 50; 1–200)
offsetintegernoNumero di record da saltare. Usa pagination.next_offset della pagina precedente. (predefinito 0; 0–…)
Restituisce{data: [{id, name, prefix, lastUsedAt, createdAt}], count, pagination}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "list_api_keys",
  "arguments": {}
}
Sola letturaget_service_health
GET /health

Controlla lo stato del servizio SendHQ

Controlla che l'API di SendHQ sia attiva e quale provider di posta è in uso. Non richiede una chiave API valida.

Nessun parametro.

Restituisce{ok, service, mailer}.
AnnotazionireadOnlyHint idempotentHint
Esempio di params per tools/call
{
  "name": "get_service_health",
  "arguments": {}
}

Inventario della copertura dell'API

Ogni operazione dell'API pubblica e lo strumento che la copre. Tutto ciò che un utente può fare nella dashboard e che ha un'API è coperto; le esclusioni riportate sotto sono intenzionali.

EndpointStrumentoNote
POST /emailssend_emailInvia un'email
POST /emails/batchsend_batchInvia fino a 100 messaggi personalizzati
GET /emailslist_emailsElenca le email inviate e ricevute
GET /emails/:idget_emailRecupera un'email e i suoi allegati
PATCH /emails/:idmark_emailAggiorna lettura, archiviazione, spam, categoria o importanza
POST /emails/:id/labelslabel_emailAggiungi o rimuovi etichette da un'email
DELETE /emails/:iddelete_emailElimina un'email conservata
GET /emails/:id/eventslist_email_eventsElenca gli eventi di consegna di un'email
GET /threads/:idget_threadRecupera una conversazione in ordine cronologico
GET /labelslist_labelsElenca le etichette con il numero di messaggi e le regole di archiviazione
POST /labelscreate_labelCrea un'etichetta, facoltativamente con regole di archiviazione automatica
GET /labels/:idget_labelRecupera un'etichetta per ID o per nome
PATCH /labels/:idupdate_labelRinomina un'etichetta, cambiane il colore o trasformala in un bucket
DELETE /labels/:iddelete_labelElimina un'etichetta senza eliminarne le email
POST /labels/:id/rulescreate_label_ruleAggiungi una regola di archiviazione automatica a un'etichetta
DELETE /labels/:id/rules/:rule_iddelete_label_ruleElimina una regola di archiviazione automatica
POST /draftscreate_draftCrea una bozza del composer
GET /draftslist_draftsElenca le bozze del composer
GET /drafts/:idget_draftRecupera una bozza e i suoi allegati
PUT /drafts/:idupdate_draftSostituisci il contenuto della bozza
DELETE /drafts/:iddelete_draftScarta una bozza
POST /drafts/:id/attachmentsupload_attachmentCarica un allegato in una bozza
GET /attachments/:iddownload_attachmentScarica un allegato privato
DELETE /attachments/:iddelete_attachmentElimina un allegato privato
GET /sending-identitieslist_sending_identitiesElenca le identità mittente verificate
GET /templateslist_templatesElenca i template ospitati
POST /templatescreate_templateCrea un template ospitato
GET /templates/:idget_templateRecupera bozze, release e utilizzo
PUT /templates/:id/draftupdate_template_draftSalva automaticamente la bozza di un template
POST /templates/:id/draftcreate_template_draftCrea una nuova bozza dalla release pubblicata
POST /templates/:id/renderrender_templateRenderizza l'output esatto del server
POST /templates/:id/testsend_template_testInvia uno snapshot di test
POST /templates/:id/publishpublish_templatePubblica una release immutabile del template
POST /templates/:id/archivearchive_templateArchivia un template
POST /templates/:id/restorerestore_templateRipristina un template archiviato
POST /domainsadd_domainAggiungi un dominio di invio
GET /domainslist_domainsElenca i domini e lo stato DNS in cache
GET /domains/:idget_domainRecupera i dettagli di configurazione del dominio
POST /domains/:id/verifyverify_domainRefresh domain and DNS verification
POST /domains/:id/inbound/setupsetup_inboundProvision inbound receiving
POST /domains/:id/inbound/verifyverify_inboundVerifica l'instradamento MX in entrata
DELETE /domains/:iddelete_domainElimina un dominio
GET /dns/providerget_dns_providerRileva il provider DNS autoritativo e gli host relativi dei record
GET /dns/domain-connect/connectget_domain_connect_linkCrea un link di consenso Domain Connect per configurare il DNS con un clic
POST /inboxescreate_inboxCrea un indirizzo in entrata
GET /inboxeslist_inboxesElenca gli indirizzi in entrata
GET /inboxes/:idget_inboxRecupera un indirizzo in entrata
PATCH /inboxes/:idupdate_inboxRinomina, attiva o disattiva una inbox
PUT /inboxes/:id/forwardingset_inbox_forwardingInoltra a un altro indirizzo la posta ricevuta da una inbox
DELETE /inboxes/:iddelete_inboxElimina una inbox conservandone i messaggi
GET /deliverability/statsdeliverability_statsRecupera le statistiche di consegna degli ultimi 30 giorni
GET /deliverability/reputationlist_sender_reputationElenca lo stato della reputazione per identità mittente esatta
GET /deliverability/accountdeliverability_accountAccount delivery rates, daily ladder, and bounce trend
GET /deliverability/domainsdeliverability_domainsPer-domain sent, delivered, hard and soft bounces, complaints, and failures
GET /deliverability/sendersdeliverability_sendersPer-From-address delivery rates
POST /deliverability/scorescore_emailScore an email's content before it is sent
GET /emails/:id/deliveryemail_deliveryDelivery timeline for one email, with bounce and complaint reasons
GET /threads/:id/deliverythread_deliveryPer-thread delivery counts and per-message failure reasons
GET /suppressionslist_suppressionsElenca le soppressioni del workspace
DELETE /suppressions/:emailremove_suppressionRimuovi una soppressione per bounce idonea
GET /blocked-recipientslist_blocked_recipientsElenca bounce, segnalazioni di spam e disiscrizioni
GET /webhooksnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooksnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:idnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
PATCH /webhooks/:idnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
DELETE /webhooks/:idnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/rotate-secretnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/testnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id/deliveriesnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /webhooks/:id/deliveries/:deliveryIdnon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
POST /webhooks/:id/deliveries/:deliveryId/retrynon espostoWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
GET /contactslist_contactsList contacts
POST /contactscreate_contactAdd a contact with its consent basis
PUT /contactsupsert_contactCreate or update a contact by email
POST /contacts/bulkbulk_update_contactsTag, move, unsubscribe, or delete many contacts at once
GET /contacts/exportnon espostoImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
GET /contacts/:idget_contactRetrieve a contact by ID or email
PATCH /contacts/:idupdate_contactUpdate a contact's name, fields, or tags, or unsubscribe it
DELETE /contacts/:iddelete_contactDelete a contact and its list memberships
POST /contact-importsimport_contactsImport contacts from CSV
GET /contact-importslist_contact_importsList recent contact imports
GET /tagslist_tagsList contact tags with how many contacts carry each
GET /contact-fieldslist_contact_fieldsList custom contact field definitions
PUT /contact-fields/:keyset_contact_fieldDefine or change a custom contact field
DELETE /contact-fields/:keydelete_contact_fieldDelete a custom field definition
GET /segmentslist_segmentsList saved segments with live counts
POST /segmentscreate_segmentSave a segment
POST /segments/previewpreview_segmentCount and sample the contacts that match unsaved conditions
GET /segments/:idget_segmentRetrieve a segment and its live count
PATCH /segments/:idupdate_segmentRename a segment or change its conditions
DELETE /segments/:iddelete_segmentDelete a segment
GET /listslist_listsList contact lists with member counts
POST /listscreate_listCreate a list with an optional signup form, welcome email, and newsletter site
GET /lists/:idget_listRetrieve a list
PATCH /lists/:idupdate_listRename a list or change its signup form, welcome email, or site
DELETE /lists/:iddelete_listDelete a list without deleting its contacts
POST /lists/:id/contactsadd_list_contactsAdd existing contacts to a list
DELETE /lists/:id/contacts/:contact_idremove_list_contactRemove a contact from a list
GET /broadcastslist_broadcastsList broadcasts
POST /broadcastscreate_broadcastCreate a broadcast draft
GET /broadcasts/:idget_broadcastRetrieve a broadcast and its delivery totals
PATCH /broadcasts/:idupdate_broadcastEdit a draft broadcast
DELETE /broadcasts/:iddelete_broadcastDelete a draft broadcast
GET /broadcasts/:id/checkscheck_broadcastRun the pre-send checks for a broadcast
POST /broadcasts/:id/testsend_broadcast_testSend a test copy of a draft
POST /broadcasts/:id/scheduleschedule_broadcastSchedule a draft to send later
POST /broadcasts/:id/unscheduleunschedule_broadcastUnschedule a draft
POST /broadcasts/:id/duplicateduplicate_broadcastCopy a broadcast into a new draft
POST /broadcasts/:id/sendsend_broadcastSend a broadcast to its audience
POST /broadcasts/:id/send-moresend_broadcast_to_moreSend a sent broadcast to more of its audience
POST /broadcasts/:id/cancelcancel_broadcastCancel a draft or sending broadcast
GET /broadcasts/:id/recipientslist_broadcast_recipientsList a broadcast's recipients, outcomes, and engagement
GET /broadcasts/:id/reportget_broadcast_reportRetrieve a broadcast's engagement report
GET /campaigns/overviewget_campaign_overviewRetrieve subscriber growth and recent broadcast performance
GET /newsletter-settingsget_newsletter_settingsRetrieve newsletter settings
PATCH /newsletter-settingsupdate_newsletter_settingsChange newsletter settings
POST /uploads/imagesnon espostoImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
GET /uploads/imageslist_uploaded_imagesList recently uploaded images
POST /eventstrack_eventRecord something a contact did
POST /events/batchnon espostoHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
GET /automationslist_automationsList automations with their 30-day totals
POST /automationscreate_automationCreate an automation as a draft
GET /automations/:keyget_automationRetrieve an automation with its emails
PATCH /automations/:keyupdate_automationEdit an automation
DELETE /automations/:keydelete_automationDelete an automation and its history
PUT /automations/:key/steps/:positionset_automation_stepCreate or change one email of an automation
DELETE /automations/:key/steps/:positiondelete_automation_stepRemove one email from an automation
PUT /automations/:key/steps/:position/variants/:localeset_automation_step_variantCreate or change a language version of an email
POST /automations/:key/steps/:position/testsend_automation_test_emailSend one email of an automation to yourself as a test
POST /automations/:key/testsend_automation_testSend every email of an automation to yourself as tests
POST /automations/:key/statusset_automation_statusTurn an automation on or off
POST /automations/:key/enrollenroll_contactAdd a contact to an automation
POST /automations/:key/exitexit_contactTake a contact out of an automation
GET /automations/:key/previewpreview_automationDry run: what each person in an automation would get now
GET /automations/overviewget_automations_overviewTotals and a daily series across every automation
GET /automations/:key/reportget_automation_reportResults of one automation, with one row per email
GET /automations/:key/peoplelist_automation_peopleList the people in an automation by what they did
GET /automations/:key/people/:contact_idget_automation_personOne person's history in an automation
POST /automations/:key/import-historynon espostoHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
GET /automation-settingsget_sending_limitsRetrieve the workspace's sending limits for automations
PUT /automation-settingsupdate_sending_limitsChange the workspace's sending limits for automations
GET /automation-librarylist_automation_templatesList the template library: ready-made lifecycle emails
GET /automation-library/:idget_automation_templateRead one template or set, with the email as it will look
POST /automation-library/:id/useuse_automation_templateCreate a draft automation from a template or set
GET /eventslist_eventsList what contacts did, newest first
GET /events/nameslist_event_namesList the kinds of event recorded in the last 30 days
POST /events/previewnon espostoThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.
GET /connectionslist_connectionsList the workspace's connections (incoming webhooks)
POST /connectionscreate_connectionCreate a connection and get its address
POST /connections/testnon espostoThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.
GET /connections/:idget_connectionRetrieve a connection with its last deliveries
PATCH /connections/:idupdate_connectionChange a connection or switch it on or off
DELETE /connections/:iddelete_connectionDelete a connection
POST /connections/:id/addressnon espostoThe address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings.
GET /accountget_accountRecupera account, utilizzo, stato della fatturazione e conteggi del workspace con una chiave API
GET /account/diagnosticsget_account_diagnosticsDiagnose sending and receiving problems in the workspace
GET /analyticsget_analyticsRecupera le analytics di invio della dashboard per 7, 30 o 90 giorni
GET /profileget_accountGemello di GET /account riservato alle sessioni; il server MCP legge la route con chiave API.
POST /billing/checkoutnon espostoPer scelta progettuale, le modifiche alla fatturazione sono disponibili solo tramite sessione e richiedono il titolare dell'account nella dashboard. Lo stato della fatturazione si può leggere con get_account.
POST /billing/cancelnon espostoPer scelta progettuale, le modifiche alla fatturazione sono disponibili solo tramite sessione e richiedono il titolare dell'account nella dashboard. Lo stato della fatturazione si può leggere con get_account.
POST /keysnon espostoEscluso intenzionalmente: un agente non deve generare né distruggere credenziali. Le chiavi le gestisce una persona nella dashboard.
GET /keyslist_api_keysElenca i metadati delle chiavi API
DELETE /keys/:idnon espostoEscluso intenzionalmente: un agente non deve generare né distruggere credenziali. Le chiavi le gestisce una persona nella dashboard.

Non disponibile per scelta

FunzionalitàEndpointMotivo
Creare, ruotare, revocare o eliminare chiavi APIPOST /keys, DELETE /keys/:idEscluso intenzionalmente: un agente non deve generare né distruggere credenziali. Le chiavi le gestisce una persona nella dashboard.
Avviare un checkout o annullare un abbonamentoPOST /billing/checkout, POST /billing/cancelPer scelta progettuale, le modifiche alla fatturazione sono disponibili solo tramite sessione e richiedono il titolare dell'account nella dashboard. Lo stato della fatturazione si può leggere con get_account.
DNS con un clic di Cloudflare (OAuth)GET /api/dns/cloudflare/connectRichiede una sessione interattiva nel browser e il consenso OAuth di Cloudflare. Usa invece i record di get_domain, gli host di get_dns_provider o get_domain_connect_link.
Registrazione, accesso, disconnessione, collegamento dell'account Google/api/auth/*Autenticazione di una persona nel browser; il server MCP si autentica con una chiave API.
Modulo di contatto del supportoPOST /api/contactModulo pubblico del sito di marketing destinato alle persone, non un'operazione del workspace.
Webhook endpoints and deliveriesGET /webhooks, POST /webhooks, GET /webhooks/:id, PATCH /webhooks/:id, DELETE /webhooks/:id, POST /webhooks/:id/rotate-secret, POST /webhooks/:id/test, GET /webhooks/:id/deliveries, GET /webhooks/:id/deliveries/:deliveryId, POST /webhooks/:id/deliveries/:deliveryId/retryWebhook endpoints are configured once by a human, in the dashboard or the REST API, and their responses carry signing secrets an agent should not hold. An agent reads the same outcomes with list_email_events, list_emails, and list_blocked_recipients.
Upload editor images and export contacts as CSVPOST /uploads/images, GET /contacts/exportImage uploads take a raw binary body and the export returns a CSV file meant for a person to download. Agents reuse uploaded images with list_uploaded_images and read the same contacts, filters, tags, and fields as JSON with list_contacts (paginated).
Import an automation's send history and record events in bulkPOST /automations/:key/import-history, POST /events/batchHistory import is a one-time migration step for the account owner and requires a dashboard session. Bulk events are for server-side backfills through the REST API; an agent records what one person did with track_event, which takes a dedupe_key for safe retries.
Move SendHQ's own win-back emails onto automations (backfill and comparison)POST /automations/platform-backfill, GET /automations/platform-compareInternal cutover tools for SendHQ's own workspace only: they answer nobody else, need its owner's dashboard session, and are not part of the public API or of /api/v1. The backfill enrols SendHQ's own accounts, so it is run by a person, one page at a time, after reading the dry run.
Replace a connection's secret addressPOST /connections/:id/addressThe address is a credential: whoever holds it can record events for the workspace. Replacing it cuts off the system that uses the old one, so a person does it in the dashboard, next to that system's own settings.
Dry runs for a sample payload and for a set of eventsPOST /connections/test, POST /events/previewThese answer the dashboard's connection and spreadsheet screens and take a request body, while this server keeps its read-only tools to GET. An agent sees what a connection did with get_connection, and what an event started with list_events.

Catalogo leggibile dalle macchine: /docs/mcp/tools.json (schemi, annotazioni, mappatura degli endpoint, esclusioni). Versione Markdown di questa pagina: /docs/mcp.md. Con la CLI installata, sendhq commands --format json stampa lo stesso catalogo.