Pour les agents IA

Serveur MCP 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
Installer et connecter (Claude Code)
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

Présentation du serveur

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.

C’est un serveur stdio local intégré au binaire CLI sendhq. Votre client MCP lance sendhq mcp comme processus enfant et communique en JSON-RPC via stdin/stdout. Chaque appel d’outil devient une requête documentée vers l’API REST de SendHQ à l’adresse https://sendhq.cc/api/v1, authentifiée avec la clé API de votre espace de travail : le serveur MCP a donc exactement les permissions de cette clé, et rien de plus.

  • 142 tools in 10 groups, generated from one catalog that is also published as tools.json.
  • Des JSON Schemas stricts : les arguments inconnus, les types incorrects et les champs obligatoires manquants sont rejetés localement avant que quoi que ce soit n’atteigne SendHQ.
  • Des erreurs structurées avec un code stable, le status HTTP, une explanation, un remedy concret et l’indication qu’une nouvelle tentative peut ou non aider.
  • Chaque outil qui envoie de vrais e-mails ou détruit des données l’indique dès les premiers mots de sa description et porte des annotations de sécurité MCP.
  • Le mode --read-only masque tous les outils d’envoi et de modification.
  • Rien n’est journalisé. stdout ne transporte que des messages de protocole ; la clé API et le contenu des messages n’apparaissent jamais dans un log.
Ce n’est pas l’endpoint MCP de documentation.SendHQ héberge aussi un petit endpoint MCP de documentation en lecture seule à l’adresse https://sendhq.cc/api/mcp (consultation des tarifs et de la documentation, sans accès au compte). Le serveur décrit sur cette page est le serveur complet, rattaché au compte ; il s’exécute en local ou via le connecteur hébergé décrit ci-dessous.

Use SendHQ in Claude, ChatGPT and Grok

Aucune installation requise : SendHQ exécute aussi ce serveur sous forme de connecteur hébergé à l’adresse https://mcp.sendhq.cc/mcp, avec les mêmes outils. Vous vous connectez avec votre compte SendHQ au lieu de coller une clé.

Claude

  1. Ouvrez Settings → Connectors et trouvez SendHQ dans l’annuaire, ou choisissez Add custom connector et collez https://mcp.sendhq.cc/mcp.
  2. Cliquez sur Connect, connectez-vous à SendHQ, vérifiez les accès demandés et cliquez sur Allow.
  3. Demandez à Claude de consulter votre boîte de réception, d’envoyer un e-mail depuis votre domaine vérifié ou d’expliquer 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.

Approbation et déconnexion

  • The request_feature tool sends a feature request to the SendHQ team with your account details, so we can follow up by email.
  • Les outils qui envoient de vrais e-mails ou suppriment des données sont signalés comme tels. C’est dans l’assistant que vous choisissez, outil par outil, s’il doit d’abord vous demander votre accord : dans Claude, choisissez Needs approval pour ces outils sous Settings → Connectors → SendHQ.
  • Le connecteur reçoit sa propre clé API, nommée d’après l’assistant (par exemple « Claude (AI connector) »). Supprimez-la sous API Keys pour le déconnecter immédiatement.
  • Il ne peut ni créer ni révoquer de clés API, ni modifier la facturation. Les pièces jointes sont envoyées et renvoyées en base64 ; il n’y a aucun accès aux fichiers locaux.
  • Sending requires an active subscription. There is no free allowance, including mail to the account owner.

Questions : postmaster@sendhq.cc. Confidentialité : sendhq.cc/privacy.

Installation

Installez le binaire sendhq (Linux, macOS et Windows, sur x86-64 et arm64). L’installateur vérifie la somme de contrôle de la version et place le binaire dans ~/.local/bin par défaut.

macOS et Linux
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
Windows PowerShell
irm https://downloads.sendhq.cc/install.ps1 | iex
Vérifier l’installation
sendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor

Créez une clé API dans le tableau de bord, à l’adresse https://sendhq.cc/app#/keys. Le serveur MCP ne peut pas créer de clés. La seule commande qui lance le serveur est :

Lancer le serveur stdio
SENDHQ_API_KEY=re_your_key sendhq mcp

En temps normal, vous ne la lancez jamais à la main : c’est le client MCP qui s’en charge. Lancée dans un terminal, elle attend du JSON-RPC sur stdin.

Configurer votre 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

Ajoutez --scope user pour le rendre disponible dans tous les projets, ou --scope project pour l’écrire dans le fichier .mcp.json du projet. Pour un .mcp.json partagé, référencez la clé depuis l’environnement au lieu de la committer ; Claude Code développe ${VAR} dans .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" }

Ou en ligne de commande : codex mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp.

Claude Desktop

Modifiez claude_desktop_config.json (macOS : ~/Library/Application Support/Claude/, Windows : %APPDATA%\Claude\) et redémarrez l’application. Les applications de bureau n’héritent pas du PATH de votre shell : utilisez donc le chemin absolu du binaire (which sendhq).

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

Tout autre client MCP

Configurez un serveur stdio avec la commande sendhq, les arguments ["mcp"] (et éventuellement "--read-only") et les variables d’environnement ci-dessous. Le serveur prend en charge les versions 2024-11-05, 2025-03-26, 2025-06-18 et 2025-11-25 du protocole MCP, et implémente initialize, ping, tools/list et tools/call. Les résultats d’outils contiennent à la fois un bloc de texte JSON et un structuredContent.

Test rapide stdio brut (à envoyer dans 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":{}}}

Il n’existe pas de transport HTTP hébergé pour le serveur rattaché au compte. Un endpoint MCP distant capable d’écrire nécessiterait un OAuth par utilisateur, que SendHQ ne propose pas ; le binaire local garde la clé sur la machine qui la détient déjà.

Environnement et options

Variable ou optionObligatoireSignification
SENDHQ_API_KEYouiClé API de l’espace de travail (re_…). Tous les outils sauf get_service_health en ont besoin. Sans elle, le serveur démarre quand même et chaque appel renvoie une auth_error structurée expliquant comment corriger le problème.
SENDHQ_API_BASE_URLnonURL de base de l’API. Valeur par défaut : https://sendhq.cc/api/v1. À n’utiliser que pour un déploiement local ou de staging. SENDHQ_BASE_URL est accepté comme ancien alias.
SENDHQ_MCP_READ_ONLYnon1, true ou yes équivaut à --read-only.
--read-onlynonN’expose que les outils qui n’envoient pas d’e-mails et ne modifient pas l’état. Les outils masqués sont également refusés s’ils sont appelés par leur nom.
SENDHQ_PROFILE / --profilenonUtilise une clé enregistrée par sendhq auth login dans le trousseau du système d’exploitation au lieu de SENDHQ_API_KEY. La variable d’environnement l’emporte si les deux existent.

La clé n’est envoyée que dans l’en-tête Authorization: Bearer, vers l’URL de base configurée. Elle n’est jamais affichée, journalisée, reprise dans les erreurs ni incluse dans les résultats d’outils.

Modèle de sécurité pour les agents

  • 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.
  • Modifie l’état. Créer ou mettre à jour des brouillons, des modèles, des domaines et des boîtes de réception, publier des modèles et lancer une vérification modifient l’espace de travail, mais n’envoient pas d’e-mail.
  • Lecture seule. Tout le reste est readOnlyHint: true et peut être appelé librement.
  • Ce serveur ne modifie jamais le DNS. add_domain renvoie des enregistrements qu’un humain doit publier ; get_domain_connect_link renvoie une URL de consentement qu’une personne doit ouvrir et approuver chez son fournisseur DNS.
  • Ce serveur ne modifie jamais la facturation. get_account se contente de lire la formule, l’utilisation et l’état de l’abonnement.
  • 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).
  • Ne changez pas d’adresse From pour contourner une pause 423, et ne réintégrez jamais des destinataires désinscrits ou ayant porté plainte.

Les clés API sont hors périmètre

Par conception, il n’existe aucun outil pour créer, modifier, faire tourner, révoquer ou supprimer des clés API. Un agent ne doit ni émettre ni détruire d’identifiants. list_api_keys renvoie uniquement les noms, les préfixes non secrets et les dates de dernière utilisation. La gestion des clés reste dans le tableau de bord, entre les mains d’un humain connecté.

Workflows

1. Premier envoi

  1. get_service_health confirme que l’API est joignable (fonctionne sans clé).
  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 liste les adresses From que vous pouvez utiliser. Si la liste est vide, suivez d’abord le workflow de domaine.
  4. Confirmez l’expéditeur, le destinataire, l’objet et le corps avec l’utilisateur, puis appelez send_email avec une idempotency_key.
  5. list_email_events avec l’id renvoyé affiche delivery, bounce, complaint ou reject dès que le fournisseur le signale (généralement en quelques secondes à quelques minutes).
Premier envoi
{
  "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. Vérification de domaine de bout en bout

  1. add_domain with name: "example.com". The result includes the DNS records (DKIM CNAMEs, domain verification, SPF, recommended DMARC).
  2. get_dns_provider avec le domain_id détecte le fournisseur DNS faisant autorité et renvoie l’hôte relatif exact à saisir pour chaque enregistrement chez ce fournisseur.
  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. Lorsque status vaut verified, les adresses du domaine apparaissent dans list_sending_identities.

3. Bounces, plaintes et suppressions

  1. list_blocked_recipients renvoie chaque adresse bloquée avec son motif (bounce, complaint, unsubscribe) ainsi qu’un décompte récapitulatif.
  2. list_suppressions renvoie les suppressions pour hard bounce et pour plainte ; deliverability_stats fournit les taux de livraison, de bounces et de plaintes sur 30 jours ; list_sender_reputation indique quelles adresses From sont bridées ou en pause.
  3. Un envoi contenant un destinataire en liste de suppression échoue avec 422 recipient_suppressed. Retirez ce destinataire et renvoyez.
  4. N’appelez remove_suppression que lorsqu’un humain confirme qu’une boîte aux lettres en bounce fonctionne désormais. Les suppressions pour plainte sont permanentes (409 complaint_suppression_locked).

4. Recevoir des e-mails entrants

  1. Le domaine (souvent un sous-domaine comme inbound.example.com) doit être vérifié.
  2. setup_inbound configure la réception et renvoie un enregistrement MX. Un humain le publie.
  3. verify_inbound jusqu’à ce que status vaille ready.
  4. create_inbox avec domain_id et local_part (par exemple support) crée support@inbound.example.com.
  5. Interrogez list_emails avec direction: "in" et unread: true (et éventuellement inbox_id). Lisez un message avec get_email, sa conversation avec get_thread, ses pièces jointes avec download_attachment, et marquez-le comme traité avec mark_email (read: true).
  6. Répondez dans le fil avec send_email et reply_to_email_id ; SendHQ définit In-Reply-To, References et le fil de discussion.

5. Webhooks et notifications d’événements

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. Diagnostiquer un échec de livraison

  1. Trouvez le message : list_emails avec direction: "out" et to ou query, ou get_email si vous avez l’identifiant. status: failed signifie que SendHQ ou le fournisseur l’a rejeté lors de la soumission ; l’erreur de l’e-mail en explique la raison.
  2. list_email_events : bounce (permanent ou transitoire, avec le diagnostic du fournisseur), complaint, reject ou delivery. L’absence d’événements signifie que le fournisseur n’a encore rien signalé ; attendez et vérifiez à nouveau.
  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 vérifie que DKIM, SPF et DMARC sont toujours publiés ; deliverability_stats montre si le problème concerne un seul message ou une tendance.
  5. Rapportez ce que montrent les preuves. Un événement delivery signifie que le serveur du destinataire a accepté le message, pas qu’il est arrivé en boîte de réception ni qu’il a été lu.

7. Gérer sa propre catégorie de tâches (libellés)

  1. create_label avec name (par exemple Agent/Orders) et skip_inbox: true. Le libellé devient alors une catégorie : le courrier reçu qui l’obtient est archivé, de sorte qu’il n’apparaît que dans le libellé, jamais dans la Boîte de réception de l’humain.
  2. Envoyez le courrier lié à la tâche avec send_email (ou send_batch) et labels: ["Agent/Orders"]. Les réponses à cette conversation héritent automatiquement du libellé et évitent la Boîte de réception.
  3. Pour le courrier qui commence en dehors de vos conversations, ajoutez une règle de classement : create_label_rule avec inbox_id (une adresse dédiée comme orders@…), from, to ou subject. Passez apply_to_existing: true pour classer le courrier déjà reçu.
  4. Traitez la catégorie : list_emails avec label: "Agent/Orders", direction: "in" et unread: true ; lisez avec get_email ou get_thread, répondez avec send_email et reply_to_email_id, puis appelez mark_email read: true une fois le message traité.
  5. Déplacez un message égaré vers la catégorie ou hors de celle-ci avec label_email (add / remove). Ajouter un libellé de catégorie à un message reçu l’archive également.
  6. En option, set_inbox_forwarding envoie une copie de tout ce que reçoit une adresse de réception vers une autre boîte aux lettres (la cible confirme d’abord par e-mail).
Envoyer dans une catégorie
{
  "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. Pièces jointes et modèles

Joignez jusqu’à 10 fichiers avec le paramètre attachments de send_email (chacun nécessite content_base64 ou un file_path local ; filename vaut par défaut le nom de base du fichier) sur une formule payante. Pour les modèles hébergés : create_template → update_template_draft → render_template pour prévisualiser avec des données d’exemple → send_template_test (envoie un vrai test) → publish_template, puis envoyez avec send_email ou send_batch en utilisant template: {key, data} et exactement un destinataire 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>"
  }
}

Résultats, pagination et erreurs

Un appel réussi renvoie l’objet JSON de l’API sous forme de structuredContent et de bloc de texte JSON. Chaque outil list_* accepte limit (1–200, 50 par défaut) et offset, et ajoute un objet pagination. Continuez à appeler avec offset: pagination.next_offset tant que has_more vaut true.

Résultat paginé
{
  "data": [
    "…"
  ],
  "count": 50,
  "pagination": {
    "offset": 0,
    "limit": 50,
    "returned": 50,
    "total": 180,
    "has_more": true,
    "next_offset": 50
  }
}

Un appel en échec renvoie isError: true avec une erreur structurée. Suivez le remedy au lieu de réessayer à l’aveugle ; ne réessayez que si retryable vaut true.

Erreur d’outil structurée
{
  "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."
  }
}

Champs d’erreur facultatifs : request_id (à citer au support), retry_after_seconds, problems (liste des violations de schéma pour invalid_arguments) et idempotent_replayed (voir Idempotence).

Idempotence

send_email et send_batch acceptent idempotency_key (200 caractères max.), envoyée dans l’en-tête Idempotency-Key. Générez une clé stable par message logique, par exemple invoice-4812-receipt.

  • Une nouvelle tentative doit réutiliser la même clé ET un corps de requête identique. La même clé avec la moindre modification (destinataire, objet, corps, en-tête, données de modèle, voire valeurs d’arguments) renvoie 409 idempotency_conflict.
  • Même clé, même corps, requête d’origine terminée : SendHQ renvoie le résultat enregistré sans renvoyer l’e-mail. C’est ainsi que l’on réessaie sans risque après un timeout ou une network_error.
  • Même clé alors que la requête d’origine est encore en cours : 409 idempotency_in_progress, à réessayer après une courte attente.
  • Un nouveau message logique nécessite une nouvelle clé.
  • Les échecs enregistrés sont eux aussi rejoués. Si la première tentative a échoué, réessayer avec la même clé renvoie ce même échec avec idempotent_replayed: true et retryable: false. Vérifiez avec list_emails (direction: out) que rien n’est parti, corrigez la cause, puis envoyez avec une nouvelle clé.
  • Le serveur ne réessaie jamais un POST de lui-même. Seuls les appels GET en lecture seule sont réessayés automatiquement (jusqu’à 3 tentatives en cas d’erreur réseau, de 429 et de 5xx).
  • send_email avec des attachments en ligne ne peut pas prendre d’idempotency_key, car il exécute plusieurs requêtes. Pour des envois de pièces jointes sûrs en cas de nouvelle tentative : create_draft → upload_attachment → send_email avec draft_id et idempotency_key.
Envoi sûr en cas de nouvelle tentative (à répéter à l’identique après un 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"
  }
}

Limites de débit et quotas

SendHQ ne publie pas de limite fixe de requêtes par seconde pour l’API. Les limites qu’un agent rencontre réellement sont des limites d’utilisation, renvoyées sous forme de 429 :

  • Livraisons mensuelles par destinataire selon la formule. Chaque adresse To, Cc et Bcc compte pour une livraison. Voir get_account → usage.recipientDeliveries par rapport à usage.emailQuotaMonth.
  • Destinataires quotidiens par adresse From exacte, selon l’état de réputation de cet expéditeur (list_sender_reputation → dailyLimit, 2 000 par défaut sur les formules payantes).
  • 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.
  • Pièces jointes : au maximum 10 fichiers et 10 MB par message ; 10 GB de transfert de pièces jointes pondéré par destinataire par mois sur les formules payantes.
  • Par requête : To + Cc + Bcc jusqu’à 100 adresses ; send_batch jusqu’à 100 messages.
  • Disjoncteur de réputation : sur une fenêtre glissante de 7 jours, des bounces ou des plaintes au-delà du seuil brident ou mettent en pause une adresse From (423 sender_paused). Elle se rétablit automatiquement une fois les taux redescendus.

quota_exhausted ne peut pas être réessayé avant la réinitialisation de la période ou un changement de formule. rate_limited peut être réessayé après retry_after_seconds ; pour les envois, réessayez avec la même idempotency_key et un corps identique.

Catalogue des erreurs

Le code est stable ; basez vos branchements sur lui plutôt que sur message.

codeHTTPRéessayer ?Signification et marche à suivre
invalid_arguments—nonLes arguments n’ont pas passé localement le JSON Schema de l’outil ; rien n’a atteint SendHQ. Corrigez les champs listés dans problems.
auth_error401nonClé API manquante, révoquée ou incorrecte. Définissez SENDHQ_API_KEY pour le processus du serveur ; c’est un humain qui crée les clés dans le tableau de bord.
subscription_required402nonNo active subscription. Nothing is sent, including to the account owner. The owner chooses a plan. Do not retry until then.
payment_required402nonLa fonctionnalité nécessite une formule payante (par exemple les pièces jointes). Envoyez sans elle ou passez à une formule supérieure.
sender_domain_not_owned403nonLe domaine From n’appartient pas à cet espace de travail. Utilisez list_sending_identities ou add_domain.
sender_domain_unverified403nonLe domaine From n’est pas encore vérifié. get_domain, publiez les enregistrements manquants, verify_domain.
domain_limit_reached403nonLimite de domaines de la formule atteinte. Supprimez un domaine inutilisé (avec approbation) ou passez à une formule supérieure.
marketing_not_enabled403nonLa classe marketing n’est pas activée pour ce domaine ou cette formule. N’utilisez transactional que si le message est réellement transactionnel.
forbidden403nonLa politique n’autorise pas l’opération. Ajustez la requête.
not_found404nonL’identifiant n’appartient pas à cet espace de travail. Listez la ressource pour trouver le bon identifiant ; restaurez d’abord les modèles archivés.
idempotency_conflict409nonClé réutilisée avec un corps différent. Renvoyez exactement la requête d’origine, ou utilisez une nouvelle clé pour un nouveau message.
idempotency_in_progress409ouiLa requête d’origine est toujours en cours. Attendez, puis réessayez avec la même clé et le même corps.
revision_conflict409nonLe brouillon du modèle a changé depuis votre lecture. get_template, fusionnez, enregistrez à nouveau.
complaint_suppression_locked409nonLe destinataire a porté plainte. Ne lui envoyez plus jamais d’e-mail.
inbound_not_ready409nonLa réception n’est pas prête. setup_inbound, publiez le MX, verify_inbound.
conflict409nonLa ressource existe déjà ou n’est pas dans le bon état. Lisez-la et ajustez.
attachments_too_large413nonPlus de 10 fichiers ou de 10 MB. Retirez ou réduisez les pièces jointes.
recipient_suppressed422nonUn destinataire a déjà généré un hard bounce ou une plainte. Retirez-le ; voir list_blocked_recipients.
recipient_unsubscribed422nonUn destinataire s’est désinscrit des e-mails marketing. Retirez-le définitivement.
validation_failed422nonContenu rejeté, par exemple des données de modèle qui ne respectent pas le contrat de variables. Corrigez l’entrée.
sender_paused423nonCette adresse From est mise en pause par le disjoncteur bounces/plaintes sur 7 jours. Arrêtez, corrigez la liste et attendez le rétablissement automatique.
account_paused423nonWorkspace 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_exhausted429nonMonthly 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_limited429ouiSlow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap.
server_error5xxouiDéfaillance temporaire de SendHQ ou du fournisseur. Appliquez un backoff et réessayez ; pour les envois, avec la même clé et le même corps. Si idempotent_replayed vaut true, utilisez une nouvelle clé après avoir confirmé que rien n’a été envoyé.
network_error—ouiRequête ou réponse perdue. Réessayez ; pour les envois, la même idempotency_key rend l’opération sûre.
invalid_request400nonRequête mal formée. Lisez message et corrigez-la.
tool_error—nonDéfaillance locale dans le serveur MCP (par exemple un file_path illisible). Lisez message.

Référence des outils

Chaque outil avec sa classe de sécurité, l’endpoint REST qu’il appelle, ses paramètres, son format de retour et un exemple d’objet params pour tools/call. Les paramètres sont exacts : le serveur rejette tout ce qui n’est pas listé.

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

E-mails et fils de discussion

Envoie de vrais e-mailssend_email
POST /emails

Envoyer un e-mail

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.

Fournissez au moins l’un des éléments suivants : html, text, template.

ParamètreTypeObligatoireDescription
fromstringouiExpéditeur, par ex. Acme <hello@example.com>. Le domaine doit être vérifié dans cet espace de travail (voir list_sending_identities). (998 caractères max.)
tostring[]ouiDestinataires. Chaque entrée est une adresse, éventuellement accompagnée d’un nom d’affichage. To+cc+bcc ne peuvent dépasser 100 au total ; chaque destination consomme un crédit de livraison. (1–100 éléments)
ccstring[]nonDestinataires en copie. (0–100 éléments)
bccstring[]nonDestinataires en copie cachée. (0–100 éléments)
subjectstringnonObjet. À omettre lors de l’envoi d’un modèle. (998 caractères max.)
textstringnonCorps en texte brut. Fournissez text, html ou template.
htmlstringnonCorps HTML. SendHQ le nettoie et en dérive le texte lorsque text est omis.
reply_tostringnonAdresse Reply-To.
headersobjectnonEn-têtes personnalisés sûrs supplémentaires (valeurs de type chaîne), par ex. {"X-Entity-Ref-ID": "123"}. Les en-têtes de routage comme From/To/Message-ID sont contrôlés par SendHQ.
message_classstringnontransactional (par défaut) ou marketing. Le mode marketing nécessite une formule ou un domaine où le marketing est activé, et ajoute la gestion des désinscriptions. (valeurs possibles : transactional, marketing)
reply_to_email_idstringnonRépondre dans une conversation existante : l’identifiant em_… du message auquel vous répondez. SendHQ définit In-Reply-To/References et le fil de discussion.
thread_idstringnonIdentifiant explicite du fil sous lequel classer le message.
draft_idstringnonEnvoie avec ce message les pièces jointes d’un brouillon enregistré (dr_…). Le brouillon est supprimé après un envoi réussi.
templateobjectnonEnvoie un modèle hébergé publié au lieu de html/texte brut. Exige exactement un destinataire to et aucun cc/bcc ; le modèle fournit l’objet. Fournissez au moins l’un des éléments suivants : id, key.
template.idstringnonIdentifiant du modèle (tmpl_…). Fournissez id ou key.
template.keystringnonClé du modèle, par exemple account-welcome. Fournissez id ou key.
template.version_idstringnonIdentifiant facultatif d’une version publiée (tmplv_…). Par défaut, la version publiée actuelle.
template.dataobjectnonValeurs des variables typées du modèle.
labelsstring[]nonNoms de libellés ou identifiants lbl_… sous lesquels classer ce message. Les noms inconnus sont créés. Les réponses de la conversation héritent des libellés, et un libellé de catégorie (skip_inbox) tient ces réponses hors de la Boîte de réception. 10 max. (0–10 éléments)
idempotency_keystringnonEn-tête Idempotency-Key (200 caractères max.). Ne la réutilisez que pour réessayer exactement cette requête. (200 caractères max.)
attachmentsobject[]nonFichiers à joindre (10 fichiers max., 10 MB au total). Chacun nécessite content_base64 (plus filename) ou un file_path local. (0–10 éléments) Fournissez au moins l’un des éléments suivants : content_base64, file_path.
attachments[].filenamestringnonNom de fichier affiché au destinataire. Obligatoire avec content_base64 ; par défaut, le nom de base de file_path. (255 caractères max.)
attachments[].content_typestringnonType MIME, par ex. application/pdf. Par défaut application/octet-stream.
attachments[].content_base64stringnonContenu du fichier en base64 standard.
attachments[].file_pathstringnonChemin absolu d’un fichier local lisible par le processus du serveur MCP.
Renvoie{id: em_…, providerMessageId, threadId, templateId, templateVersionId, isTest}. Accepté ne veut pas dire délivré : vérifiez ensuite avec list_email_events.
Exemple de params 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"
  }
}
Envoie de vrais e-mailssend_batch
POST /emails/batch

Envoyer un lot d’e-mails personnalisés

SENDS REAL EMAIL. Envoie de 1 à 100 messages indépendants en une seule requête (à utiliser pour la personnalisation de modèle par destinataire). Chaque élément a la même forme que send_email (sans attachments/idempotency_key). Les éléments réussissent ou échouent individuellement : HTTP 207 signifie un succès partiel ; examinez chaque data[i].ok et data[i].error. Une seule idempotency_key couvre l’ensemble du corps du lot.

ParamètreTypeObligatoireDescription
emailsobject[]ouiMessages à envoyer. (1–100 éléments) Fournissez au moins l’un des éléments suivants : html, text, template.
idempotency_keystringnonIdempotency-Key pour l’ensemble du lot (200 caractères max.). (200 caractères max.)
Renvoie{data: [{index, ok, id?, error?: {message, status}}], count, successful, failed}.
Exemple de params 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"
  }
}
Lecture seulelist_emails
GET /emails

Lister et rechercher des e-mails

Liste les e-mails envoyés (direction: out) et reçus (direction: in), du plus récent au plus ancien, avec filtres. Le courrier reçu est classé : lisez la boîte de réception humaine avec direction: in, archived: false, category: primary ; faites le tri avec important: true ; le spam est masqué sauf avec category: spam ou include_spam: true. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
directionstringnonin pour le courrier reçu, out pour le courrier envoyé. (valeurs possibles : in, out)
statusstringnonFiltre de statut, par ex. queued, sent, delivered, bounced, complained, failed.
domainstringnonUniquement les messages de ce domaine, ou d’une liste de domaines séparés par des virgules (correspondance avec n’importe lequel).
inbox_idstringnonUniquement les messages reçus par cette boîte de réception (inb_…).
labelstringnonUniquement les messages portant ce libellé : un identifiant de libellé lbl_… ou son nom exact, ou une liste séparée par des virgules (correspondance avec n’importe lequel). Utilisez list_labels pour voir les dossiers.
archivedbooleannonfalse = vue Boîte de réception (courrier reçu non archivé), true = courrier archivé uniquement. À omettre pour tout le courrier.
categorystringnonprimary (personnes), updates (newsletters, envois en masse, e-mails automatisés) ou spam ; ou une liste séparée par des virgules. Le spam est masqué sauf demande explicite.
importantbooleannontrue = uniquement les messages marqués importants (réponses aux conversations que vous avez lancées et expéditeurs marqués importants).
include_spambooleannonInclure le spam dans les résultats (pour les recherches dans tous les dossiers).
fromstringnonL’adresse de l’expéditeur contient cette valeur.
tostringnonL’adresse du destinataire contient cette valeur.
unreadbooleannontrue = non lus uniquement, false = lus uniquement.
afterstringnonHorodatage ISO-8601 ; uniquement les messages créés après celui-ci. (date-time)
beforestringnonHorodatage ISO-8601 ; uniquement les messages créés avant celui-ci. (date-time)
querystringnonRecherche plein texte dans les objets, les corps, les adresses d’expéditeur/destinataire et les noms des pièces jointes. (200 caractères max.)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [résumés d’e-mails], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}
Lecture seuleget_email
GET /emails/:email_id

Obtenir un e-mail

Récupère un message avec ses en-têtes, son corps html/texte, son statut, les métadonnées du fil et celles des pièces jointes (téléchargez les octets avec download_attachment).

ParamètreTypeObligatoireDescription
email_idstringouiIdentifiant de l’e-mail (commence par em_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
RenvoieObjet e-mail : {id, direction, status, from, to, cc, bcc, subject, html, text, threadId, messageId, providerMessageId, readAt, createdAt, attachments: [{id, filename, contentType, sizeBytes, available}]}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}
Modifie l’étatmark_email
PATCH /emails/:email_id

Marquer comme lu, archivé, spam ou important

Met à jour un message : read, archived, category (primary, updates, spam ; courrier reçu uniquement) et important. Signaler un spam ou marquer un message important renseigne SendHQ sur cet expéditeur pour ses futurs e-mails ; passez learn: false pour ne modifier que ce message. Passez au moins un champ.

ParamètreTypeObligatoireDescription
email_idstringouiIdentifiant de l’e-mail (commence par em_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
readbooleannontrue = lu, false = non lu.
archivedbooleannontrue = archiver (hors de la Boîte de réception), false = remettre dans la Boîte de réception.
categorystringnonDéplace un message reçu vers primary, updates ou spam. (valeurs possibles : primary, updates, spam)
importantbooleannonMarquer ou démarquer le message comme important.
learnbooleannonfalse = ne pas mémoriser ce verdict pour l’expéditeur (true par défaut).
RenvoieL’objet e-mail mis à jour.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}
Destructifdelete_email
DELETE /emails/:email_id

Supprimer un e-mail

DESTRUCTIVE : supprime définitivement de SendHQ un message conservé et ses pièces jointes stockées. Cela ne rappelle pas un message déjà délivré.

ParamètreTypeObligatoireDescription
email_idstringouiIdentifiant de l’e-mail (commence par em_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}
Lecture seulelist_email_events
GET /emails/:email_id/events

Lister les événements de livraison d’un e-mail

Événements du fournisseur pour un message envoyé : delivery, bounce, complaint, reject, open, click. C’est la preuve qu’un message a été délivré, ou la raison de son échec. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
email_idstringouiIdentifiant de l’e-mail (commence par em_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [{event_type, recipient, reason, created_at, …}], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}
Lecture seuleget_thread
GET /threads/:thread_id

Obtenir une conversation

Récupère tous les messages d’une conversation dans l’ordre chronologique (envoyés et reçus), chacun avec les métadonnées de ses pièces jointes.

ParamètreTypeObligatoireDescription
thread_idstringouiIdentifiant du fil (généralement l’identifiant em_… du premier message ; voir threadId sur n’importe quel e-mail). (128 caractères max.)
Renvoie{id, subject, data: [e-mails]}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
email_idstringoui
limitintegernon
offsetintegernon
Returns{emailId, status, timeline, count, limit, offset}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
thread_idstringoui
Returns{threadId, delivered, bounced, complained, failed, messages}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "thread_delivery",
  "arguments": {
    "thread_id": "thr_123"
  }
}

Libellés et règles de classement automatique

Lecture seulelist_labels
GET /labels

Lister les libellés

Liste les libellés (dossiers) de l’espace de travail avec leur nombre total de messages et de non-lus, ainsi que leurs règles de classement automatique. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [{id, name, color, totalCount, unreadCount, rules: [...]}], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_labels",
  "arguments": {}
}
Lecture seuleget_label
GET /labels/:label_id

Obtenir un libellé

Récupère un libellé avec ses compteurs et ses règles de classement automatique.

ParamètreTypeObligatoireDescription
label_idstringouiIdentifiant du libellé (commence par lbl_) ou nom exact du libellé. (128 caractères max.)
RenvoieObjet libellé.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}
Modifie l’étatcreate_label
POST /labels

Créer un libellé

Crée un libellé de type dossier. Définissez skip_inbox: true pour en faire une catégorie appartenant à un agent : envoyez avec labels: [name] et les réponses sont classées sous le libellé et tenues hors de la Boîte de réception. Des règles de classement automatique facultatives classent le nouveau courrier envoyé/reçu (chaque condition d’une règle doit correspondre). Définissez apply_to_existing pour classer aussi le courrier déjà conservé.

ParamètreTypeObligatoireDescription
namestringouiNom du libellé, par ex. Billing ou Clients/Acme. Unique par espace de travail (insensible à la casse). (64 caractères max.)
colorstringnonCouleur hexadécimale, par exemple #1a73e8. Facultatif.
skip_inboxbooleannonMode catégorie : le courrier reçu qui obtient ce libellé (par une règle, par une réponse à une conversation envoyée avec ce libellé, ou manuellement) est archivé, de sorte qu’il n’apparaît que dans le libellé, pas dans la Boîte de réception.
rulesobject[]nonRègles de classement automatique facultatives (20 max.). Chacune nécessite au moins l’un des champs inbox_id, from, to, subject. (0–20 éléments)
rules[].directionstringnonUniquement le courrier in (reçu) ou out (envoyé). À omettre pour les deux. (valeurs possibles : in, out)
rules[].inbox_idstringnonUniquement le courrier reçu par cette boîte de réception (inb_…). Classe chaque adresse de réception dans son propre dossier.
rules[].fromstringnonL’expéditeur contient ce texte (insensible à la casse), par ex. @stripe.com. (200 caractères max.)
rules[].tostringnonTo/Cc contient ce texte (insensible à la casse). (200 caractères max.)
rules[].subjectstringnonL’objet contient ce texte (insensible à la casse). (200 caractères max.)
rules[].skip_inboxbooleannonArchive le courrier reçu correspondant pour qu’il n’apparaisse que dans le dossier du libellé, pas dans la Boîte de réception.
apply_to_existingbooleannonClasse aussi le courrier déjà conservé qui correspond aux règles.
RenvoieLe libellé créé avec ses règles.
Exemple de params tools/call
{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}
Modifie l’étatupdate_label
PATCH /labels/:label_id

Renommer un libellé, changer sa couleur ou en faire une catégorie

Renomme un libellé, change sa couleur ou active/désactive le mode catégorie (skip_inbox). Activer le mode catégorie archive le courrier reçu déjà présent dans le libellé.

ParamètreTypeObligatoireDescription
label_idstringouiIdentifiant du libellé (commence par lbl_) ou nom exact du libellé. (128 caractères max.)
namestringnonNouveau nom. (64 caractères max.)
colorstringnonNouvelle couleur hexadécimale.
skip_inboxbooleannonMode catégorie : le courrier reçu qui obtient ce libellé (par une règle, par une réponse à une conversation envoyée avec ce libellé, ou manuellement) est archivé, de sorte qu’il n’apparaît que dans le libellé, pas dans la Boîte de réception.
RenvoieLe libellé mis à jour.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}
Destructifdelete_label
DELETE /labels/:label_id

Supprimer un libellé

DESTRUCTIVE : supprime un libellé et ses règles. Les e-mails eux-mêmes sont conservés ; ils perdent seulement ce libellé.

ParamètreTypeObligatoireDescription
label_idstringouiIdentifiant du libellé (commence par lbl_) ou nom exact du libellé. (128 caractères max.)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}
Modifie l’étatcreate_label_rule
POST /labels/:label_id/rules

Ajouter une règle de classement automatique

Ajoute une règle à un libellé pour que le nouveau courrier correspondant soit classé automatiquement. Chaque condition définie doit correspondre. Utilisez inbox_id pour donner à une adresse de réception son propre dossier ; ajoutez skip_inbox pour tenir ce courrier hors de la Boîte de réception.

ParamètreTypeObligatoireDescription
label_idstringouiIdentifiant du libellé (commence par lbl_) ou nom exact du libellé. (128 caractères max.)
directionstringnonUniquement le courrier in (reçu) ou out (envoyé). À omettre pour les deux. (valeurs possibles : in, out)
inbox_idstringnonUniquement le courrier reçu par cette boîte de réception (inb_…). Classe chaque adresse de réception dans son propre dossier.
fromstringnonL’expéditeur contient ce texte (insensible à la casse), par ex. @stripe.com. (200 caractères max.)
tostringnonTo/Cc contient ce texte (insensible à la casse). (200 caractères max.)
subjectstringnonL’objet contient ce texte (insensible à la casse). (200 caractères max.)
skip_inboxbooleannonArchive le courrier reçu correspondant pour qu’il n’apparaisse que dans le dossier du libellé, pas dans la Boîte de réception.
apply_to_existingbooleannonClasse aussi le courrier déjà conservé qui correspond.
Renvoie{id: lrule_…, labelId, direction, inboxId, from, to, subject, skipInbox}.
Exemple de params tools/call
{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}
Destructifdelete_label_rule
DELETE /labels/:label_id/rules/:rule_id

Supprimer une règle de classement automatique

DESTRUCTIVE : retire une règle de classement automatique. Le courrier déjà classé conserve son libellé.

ParamètreTypeObligatoireDescription
label_idstringouiIdentifiant du libellé (commence par lbl_) ou nom exact du libellé. (128 caractères max.)
rule_idstringouiIdentifiant de la règle (commence par lrule_), obtenu via get_label. (128 caractères max.)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}
Modifie l’étatlabel_email
POST /emails/:email_id/labels

Ajouter ou retirer des libellés sur un e-mail

Déplace un message entre dossiers : ajoute et/ou retire des libellés par nom ou par identifiant lbl_…. Les noms inconnus dans add sont créés, sauf si create vaut false.

ParamètreTypeObligatoireDescription
email_idstringouiIdentifiant de l’e-mail (commence par em_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
addstring[]nonLibellés à ajouter. (0–10 éléments)
removestring[]nonLibellés à retirer. (0–10 éléments)
createbooleannonCrée les libellés inconnus dans add (true par défaut).
RenvoieL’e-mail mis à jour avec ses labels.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

Brouillons, pièces jointes et identités d’expéditeur

Lecture seulelist_sending_identities
GET /sending-identities

Lister les identités d’expéditeur vérifiées

Adresses et domaines depuis lesquels cet espace de travail peut envoyer dès maintenant (domaines vérifiés, leur From par défaut et adresses des boîtes de réception actives). À appeler avant send_email pour choisir un from valide.

Aucun paramètre.

Renvoie{domains: [noms des domaines vérifiés], addresses: [adresses d’expéditeur], localParts: [...]}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_sending_identities",
  "arguments": {}
}
Modifie l’étatcreate_draft
POST /drafts

Créer un brouillon

Crée un brouillon de rédaction. Les brouillons contiennent les pièces jointes : créez un brouillon, appelez upload_attachment, puis send_email avec draft_id. N’envoie rien.

ParamètreTypeObligatoireDescription
fromstringnonAdresse d’expéditeur sur un domaine vérifié (peut rester vide pendant la rédaction).
tostring[]nonDestinataires. (0–100 éléments)
ccstring[]nonDestinataires en copie. (0–100 éléments)
bccstring[]nonDestinataires en copie cachée. (0–100 éléments)
subjectstringnonObjet. (998 caractères max.)
htmlstringnonCorps HTML.
textstringnonCorps en texte brut.
reply_to_email_idstringnonIdentifiant de l’e-mail auquel ce brouillon répond.
thread_idstringnonIdentifiant du fil auquel appartient ce brouillon.
RenvoieObjet brouillon {id: dr_…, from, to, cc, bcc, subject, html, text, attachments: []}.
Exemple de params tools/call
{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}
Lecture seulelist_drafts
GET /drafts

Lister les brouillons

Liste les brouillons de rédaction, du plus récemment modifié au plus ancien. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [brouillons], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_drafts",
  "arguments": {}
}
Lecture seuleget_draft
GET /drafts/:draft_id

Obtenir un brouillon

Récupère un brouillon avec les métadonnées de ses pièces jointes.

ParamètreTypeObligatoireDescription
draft_idstringouiIdentifiant du brouillon (commence par dr_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
RenvoieObjet brouillon avec ses attachments.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
Modifie l’étatupdate_draft
PUT /drafts/:draft_id

Remplacer le contenu d’un brouillon

Remplace le contenu et les destinataires d’un brouillon. Il s’agit d’un remplacement complet : les champs omis sont effacés ; lisez donc d’abord get_draft et envoyez tous les champs à conserver. Les pièces jointes ne sont pas affectées.

ParamètreTypeObligatoireDescription
draft_idstringouiIdentifiant du brouillon (commence par dr_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
fromstringnonAdresse d’expéditeur sur un domaine vérifié (peut rester vide pendant la rédaction).
tostring[]nonDestinataires. (0–100 éléments)
ccstring[]nonDestinataires en copie. (0–100 éléments)
bccstring[]nonDestinataires en copie cachée. (0–100 éléments)
subjectstringnonObjet. (998 caractères max.)
htmlstringnonCorps HTML.
textstringnonCorps en texte brut.
reply_to_email_idstringnonIdentifiant de l’e-mail auquel ce brouillon répond.
thread_idstringnonIdentifiant du fil auquel appartient ce brouillon.
RenvoieL’objet brouillon mis à jour.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}
Destructifdelete_draft
DELETE /drafts/:draft_id

Abandonner un brouillon

DESTRUCTIVE : abandonne un brouillon et supprime définitivement ses pièces jointes stockées.

ParamètreTypeObligatoireDescription
draft_idstringouiIdentifiant du brouillon (commence par dr_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
Modifie l’étatupload_attachment
POST /drafts/:draft_id/attachments

Téléverser une pièce jointe dans un brouillon

Téléverse un fichier dans un brouillon (10 fichiers et 10 MB au total par message au maximum). Fournissez content_base64 ou un file_path local. Les pièces jointes nécessitent une formule payante au moment de l’envoi.

Fournissez au moins l’un des éléments suivants : content_base64, file_path.

ParamètreTypeObligatoireDescription
draft_idstringouiIdentifiant du brouillon (commence par dr_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
filenamestringnonNom de fichier affiché au destinataire. Par défaut, le nom de base de file_path. (255 caractères max.)
content_typestringnonType MIME, par ex. application/pdf. Par défaut application/octet-stream.
content_base64stringnonContenu du fichier en base64 standard.
file_pathstringnonChemin absolu d’un fichier local lisible par le processus du serveur MCP.
Renvoie{id: att_…, filename, contentType, sizeBytes, available}.
Exemple de params tools/call
{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}
Lecture seuledownload_attachment
GET /attachments/:attachment_id

Télécharger une pièce jointe

Télécharge une pièce jointe privée (envoyée, reçue ou de brouillon). Renvoie le contenu en base64, ou écrit le fichier lorsque save_to_path est défini (refuse d’écraser un fichier sauf si overwrite vaut true).

ParamètreTypeObligatoireDescription
attachment_idstringouiIdentifiant de la pièce jointe (commence par att_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
save_to_pathstringnonChemin local absolu facultatif où écrire le fichier au lieu de renvoyer du base64.
overwritebooleannonAutorise le remplacement d’un fichier existant à save_to_path. false par défaut.
Renvoie{attachment_id, filename, content_type, size_bytes, content_base64} ou {attachment_id, filename, content_type, size_bytes, saved_to}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}
Destructifdelete_attachment
DELETE /attachments/:attachment_id

Supprimer une pièce jointe

DESTRUCTIVE : supprime définitivement une pièce jointe stockée (par exemple pour retirer un fichier d’un brouillon avant l’envoi).

ParamètreTypeObligatoireDescription
attachment_idstringouiIdentifiant de la pièce jointe (commence par att_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

Modèles hébergés

Lecture seulelist_templates
GET /templates

Lister les modèles hébergés

Liste les modèles d’e-mails hébergés avec leur état de publication et leur utilisation. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
lifecyclestringnonactive (par défaut), archived ou all. (valeurs possibles : active, archived, all)
querystringnonRecherche par nom ou par clé. (120 caractères max.)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [modèles], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}
Modifie l’étatcreate_template
POST /templates

Créer un modèle hébergé

Crée un modèle avec un brouillon modifiable, éventuellement à partir d’un modèle de départ (welcome, reset, receipt ou blank). Publiez-le avant d’envoyer par clé.

ParamètreTypeObligatoireDescription
namestringouiNom lisible. (120 caractères max.)
keystringnonClé d’envoi stable : lettres minuscules, chiffres, traits d’union ; commence par une lettre (2 à 64 caractères). Dérivée du nom si elle est omise.
starterstringnonContenu de départ. (valeurs possibles : blank, welcome, reset, receipt)
Renvoie{template, draft, activeVersion, versions, usage}.
Exemple de params tools/call
{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}
Lecture seuleget_template
GET /templates/:template_id

Obtenir un modèle

Récupère le brouillon actuel d’un modèle (avec sa revision), la version publiée active, l’historique des versions et l’utilisation. Accepte un identifiant ou une clé.

ParamètreTypeObligatoireDescription
template_idstringouiIdentifiant (tmpl_…) ou clé du modèle. (128 caractères max.)
Renvoie{template, draft: {id, revision, subjectTemplate, htmlTemplate, textTemplate, variables, sampleData, …} | null, activeVersion, versions, usage}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Modifie l’étatupdate_template_draft
PUT /templates/:template_id/draft

Enregistrer un brouillon de modèle

Enregistre le brouillon modifiable du modèle avec une concurrence optimiste : passez la revision actuelle obtenue via get_template (409 signifie que quelqu’un d’autre a enregistré avant vous ; relisez et réessayez). Il s’agit d’un remplacement complet du contenu du brouillon : les champs omis sont effacés, envoyez donc tous les champs à conserver. Utilisez des espaces réservés {{variable}}.

ParamètreTypeObligatoireDescription
template_idstringouiIdentifiant ou clé du modèle. (128 caractères max.)
revisionintegerouiRévision actuelle du brouillon, obtenue via get_template. (1–…)
namestringnonNom du modèle. (120 caractères max.)
subject_templatestringnonObjet avec espaces réservés. (998 caractères max.)
preheader_templatestringnonTexte d’aperçu. (240 caractères max.)
html_templatestringnonCorps HTML avec espaces réservés.
text_templatestringnonCorps en texte brut avec espaces réservés.
fromstringnonExpéditeur par défaut pour les envois de ce modèle.
reply_tostringnonReply-To par défaut.
variablesobject[]nonContrat de variables typées. Chaque élément : {key (minuscules/tirets bas), label, type: text|number|url|boolean, required (true par défaut), fallback, description}.
variables[].keystringoui
variables[].labelstringnon
variables[].typestringnon(valeurs possibles : text, number, url, boolean)
variables[].requiredbooleannon
variables[].fallbackanynon
variables[].descriptionstringnon
sample_dataobjectnonValeurs d’exemple utilisées pour les aperçus et les tests.
Renvoie{template, draft: {revision: next}, validation: {valid, findings}}.
Exemple de params 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"
    }
  }
}
Modifie l’étatcreate_template_draft
POST /templates/:template_id/draft

Créer un nouveau brouillon à partir de la version publiée

Crée un nouveau brouillon modifiable copié à partir de la version publiée actuelle (409 si un brouillon existe déjà ou si rien n’est publié).

ParamètreTypeObligatoireDescription
template_idstringouiIdentifiant ou clé du modèle. (128 caractères max.)
Renvoie{draft}.
Exemple de params tools/call
{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Lecture seulerender_template
POST /templates/:template_id/render

Générer un aperçu de modèle

Génère le rendu exact produit par le serveur (subject, html, text) pour le brouillon, la version publiée ou une version précise, avec les données fournies. N’envoie rien. Renvoie 422 avec des findings lorsque les données ne respectent pas le contrat de variables.

ParamètreTypeObligatoireDescription
template_idstringouiIdentifiant ou clé du modèle. (128 caractères max.)
version_idstringnonIdentifiant de version facultatif ; par défaut le brouillon, puis la version publiée.
dataobjectnonValeurs des variables ; par défaut, les données d’exemple de la version.
Renvoie{subject, html, text, preheader, versionId, versionNumber, isDraft, findings}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}
Envoie de vrais e-mailssend_template_test
POST /templates/:template_id/test

Envoyer un e-mail de test d’un modèle

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.

ParamètreTypeObligatoireDescription
template_idstringouiIdentifiant ou clé du modèle. (128 caractères max.)
tostring[]ouiDestinataires du test. (1–100 éléments)
fromstringnonExpéditeur sur un domaine vérifié ; par défaut, le From du modèle.
version_idstringnonIdentifiant de version facultatif.
dataobjectnonValeurs des variables ; par défaut, les données d’exemple.
Renvoie{id: em_…, providerMessageId, threadId, isTest: true}.
Exemple de params tools/call
{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}
Modifie l’étatpublish_template
POST /templates/:template_id/publish

Publier une version de modèle

Publie le brouillon actuel sous forme de version immuable, que send_email utilisera avec template.key. Échoue avec des findings 422 en cas d’erreurs de validation, ou avec 409 si la publication casserait le contrat de variables en vigueur d’un modèle déjà utilisé en production.

ParamètreTypeObligatoireDescription
template_idstringouiIdentifiant ou clé du modèle. (128 caractères max.)
Renvoie{template, published}.
Exemple de params tools/call
{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Modifie l’étatarchive_template
POST /templates/:template_id/archive

Archiver un modèle

Bloque les nouveaux envois utilisant ce modèle (l’historique est conservé ; réversible avec restore_template). Toute intégration qui envoie avec cette clé commencera à échouer avec une 404.

ParamètreTypeObligatoireDescription
template_idstringouiIdentifiant ou clé du modèle. (128 caractères max.)
Renvoie{template}.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Modifie l’étatrestore_template
POST /templates/:template_id/restore

Restaurer un modèle archivé

Réactive un modèle archivé.

ParamètreTypeObligatoireDescription
template_idstringouiIdentifiant ou clé du modèle. (128 caractères max.)
Renvoie{template}.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

Domaines et DNS

Lecture seulelist_domains
GET /domains

Lister les domaines

Liste les domaines d’envoi avec leur setup_status global (verified | checking | pending), l’état DNS de chaque enregistrement et l’état de la réception. Peut être lent : les domaines non vérifiés sont revérifiés en direct. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [domaines avec leurs enregistrements], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_domains",
  "arguments": {}
}
Lecture seuleget_domain
GET /domains/:domain_id

Obtenir les détails de configuration d’un domaine

Récupère un domaine avec les enregistrements DNS exacts à publier (type, nom, valeur), l’état en direct de chaque enregistrement vu par deux résolveurs publics, les dns_issues avec leurs correctifs et l’état de la réception.

ParamètreTypeObligatoireDescription
domain_idstringouiIdentifiant du domaine (commence par dom_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{id, name, status, setup_status, dns_propagating, records: [{type, name, value, verified, dns_state}], dns_issues: [{code, message, …}], inbound_domain, inbound_status}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Modifie l’étatadd_domain
POST /domains

Ajouter un domaine d’envoi

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.

ParamètreTypeObligatoireDescription
namestringouiNom de domaine nu, par ex. example.com ou mail.example.com. (253 caractères max.)
default_fromstringnonAdresse d’expéditeur par défaut facultative sur ce domaine.
Renvoie{id: dom_…, name, status: pending, records: [...], ses: {configured}}.
Exemple de params tools/call
{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}
Modifie l’étatverify_domain
POST /domains/:domain_id/verify

Vérifier un domaine

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.

ParamètreTypeObligatoireDescription
domain_idstringouiIdentifiant du domaine (commence par dom_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{domain, checks: {ses, dkim, dkim_status}, status: verified|pending}.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Destructifdelete_domain
DELETE /domains/:domain_id

Supprimer un domaine

DESTRUCTIVE : retire le domaine de l’espace de travail, y compris sa route de réception. Les envois depuis ce domaine échouent immédiatement après. Les enregistrements DNS chez votre fournisseur DNS ne sont pas supprimés.

ParamètreTypeObligatoireDescription
domain_idstringouiIdentifiant du domaine (commence par dom_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Lecture seuleget_dns_provider
GET /dns/provider

Détecter le fournisseur DNS et les hôtes des enregistrements

Détecte le fournisseur DNS faisant autorité pour le domaine et renvoie l’hôte relatif à saisir chez ce fournisseur pour chaque enregistrement, l’enregistrement DMARC recommandé, des indications pour le MX entrant, et si la configuration en un clic (Domain Connect) est disponible.

ParamètreTypeObligatoireDescription
domain_idstringouiIdentifiant du domaine (commence par dom_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{detectionStatus, detected, zone, nameservers, recordHosts: {recordId: host}, inbound, recommendations, authentication, providers: {domainConnect: {available, providerName}}}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

E-mails entrants

Modifie l’étatsetup_inbound
POST /domains/:domain_id/inbound/setup

Activer la réception d’e-mails pour un domaine

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.

ParamètreTypeObligatoireDescription
domain_idstringouiIdentifiant du domaine (commence par dom_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{domain: domaine de réception, status: dns_pending|ready, record: {type: MX, name, value}}.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Modifie l’étatverify_inbound
POST /domains/:domain_id/inbound/verify

Vérifier le MX entrant

Revérifie l’enregistrement MX entrant. Le statut passe à ready lorsque les deux résolveurs publics le voient.

ParamètreTypeObligatoireDescription
domain_idstringouiIdentifiant du domaine (commence par dom_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{domain, status: ready|dns_pending|propagating|checking, record}.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Lecture seulelist_inboxes
GET /inboxes

Lister les adresses de réception

Liste les adresses de réception, éventuellement pour un seul domaine. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
domain_idstringnonFiltre facultatif par identifiant de domaine.
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [{id, address, name, status, domainId}], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Lecture seuleget_inbox
GET /inboxes/:inbox_id

Obtenir une boîte de réception

Récupère une adresse de réception.

ParamètreTypeObligatoireDescription
inbox_idstringouiIdentifiant de la boîte de réception (commence par inb_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
RenvoieObjet boîte de réception.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}
Modifie l’étatcreate_inbox
POST /inboxes

Créer une adresse de réception

Crée une adresse comme support@<receiving domain> sur un domaine dont l’état de réception est ready (lancez d’abord setup_inbound et verify_inbound). Le courrier reçu apparaît dans list_emails avec la direction in.

ParamètreTypeObligatoireDescription
domain_idstringouiIdentifiant du domaine (commence par dom_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
local_partstringouiPartie avant le @, par ex. support. (64 caractères max.)
namestringnonNom d’affichage facultatif.
Renvoie{id: inb_…, address, name, status: active}.
Exemple de params tools/call
{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}
Modifie l’étatupdate_inbox
PATCH /inboxes/:inbox_id

Renommer, activer ou désactiver une boîte de réception

Renomme une boîte de réception ou définit son statut sur active / disabled.

ParamètreTypeObligatoireDescription
inbox_idstringouiIdentifiant de la boîte de réception (commence par inb_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
namestringnonNouveau nom d’affichage.
statusstringnonNouveau statut. (valeurs possibles : active, disabled)
RenvoieLa boîte de réception mise à jour.
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}
Envoie de vrais e-mailsset_inbox_forwarding
PUT /inboxes/:inbox_id/forwarding

Transférer une boîte de réception vers une autre adresse

SENDS REAL EMAIL en cas de transfert vers une personne autre que le propriétaire du compte : définit où le courrier reçu par une boîte de réception est transféré. L’adresse du propriétaire est activée immédiatement ; toute autre adresse reçoit un e-mail de confirmation et le transfert reste pending jusqu’à ce que quelqu’un confirme à cette adresse. Passez forward_to: null pour désactiver le transfert. Les copies transférées partent de l’adresse de la boîte de réception, avec l’expéditeur d’origine en Reply-To.

ParamètreTypeObligatoireDescription
inbox_idstringouiIdentifiant de la boîte de réception (commence par inb_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
forward_tostring,nullouiAdresse e-mail cible du transfert, ou null pour désactiver le transfert. (254 caractères max.)
RenvoieLa boîte de réception avec forwardTo et forwardStatus (off, pending ou active).
AnnotationsidempotentHint
Exemple de params tools/call
{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}
Destructifdelete_inbox
DELETE /inboxes/:inbox_id

Supprimer une boîte de réception

DESTRUCTIVE : supprime une adresse de réception. Le courrier déjà reçu est conservé ; le nouveau courrier envoyé à cette adresse n’y est plus classé.

ParamètreTypeObligatoireDescription
inbox_idstringouiIdentifiant de la boîte de réception (commence par inb_), tel que renvoyé par un outil de liste ou de création. (128 caractères max.)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

Délivrabilité, bounces et suppressions

Lecture seuledeliverability_stats
GET /deliverability/stats

Obtenir les statistiques de livraison sur 30 jours

Totaux sur 30 jours pour l’ensemble de l’espace de travail : sent, delivery, bounce, complaint, reject, open, click et deliveryRate (%).

Aucun paramètre.

Renvoie{window: 30d, sent, delivery, bounce, complaint, reject, open, click, deliveryRate}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
daysintegernon(one of 7, 30, 90)
Returns{days, trend, rolling7d, thresholds, ladder}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
daysintegernon
domainstringnon
limitintegernon
offsetintegernon
Returns{days, data, count, limit, offset}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
daysintegernon
domainstringnon
limitintegernon
offsetintegernon
Returns{days, data, count, limit, offset}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
subjectstringnonThe subject line.
htmlstringnonThe HTML as written, before SendHQ adds its footer or tracking. (max 2000000 chars)
textstringnonThe plain-text part. Compared with the HTML when both are given; scored on its own when there is no HTML. (max 2000000 chars)
fromstringnonThe 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}]}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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>"
  }
}
Lecture seulelist_sender_reputation
GET /deliverability/reputation

Lister la réputation des expéditeurs

État de réputation par adresse From exacte : active, throttled (limite quotidienne abaissée) ou paused (les envois renvoient 423), avec le motif et la limite quotidienne. À consulter lorsque les envois échouent avec 423 ou 429. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [{sender, status, dailyLimit, reason, cleanSince, warnedAt, pausedAt, evaluatedAt}], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_sender_reputation",
  "arguments": {}
}
Lecture seulelist_suppressions
GET /suppressions

Lister les suppressions

Liste de suppression de l’espace de travail : destinataires bloqués après un bounce permanent ou une plainte pour spam. Les envois vers eux échouent avec 422. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [{email, reason, detail, created_at}], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_suppressions",
  "arguments": {}
}
Destructifremove_suppression
DELETE /suppressions/:email

Retirer une suppression pour bounce

DESTRUCTIVE (affaiblit un blocage de sécurité) : retire une suppression pour bounce afin que l’adresse puisse de nouveau recevoir des e-mails. Ne le faites que lorsque l’humain confirme que l’adresse est désormais valide. Les suppressions pour plainte ne peuvent pas être retirées (409).

ParamètreTypeObligatoireDescription
emailstringouiAdresse du destinataire en liste de suppression. (320 caractères max.)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}
Lecture seulelist_blocked_recipients
GET /blocked-recipients

Lister les destinataires bloqués

Tous les destinataires que SendHQ refusera : bounces, plaintes et désinscriptions marketing par domaine, avec un récapitulatif par type. Lit au maximum les 500 plus récents. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [{email, domain, kind: bounce|complaint|unsubscribe, reason, detail, source, status, created_at}], count, summary: {total, bounce, complaint, unsubscribe}, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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}.

ParamètreTypeObligatoireDescription
list_idstringnonOnly members of this list (lst_…).
statusstringnonOnly 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)
querystringnonEmail or name contains this text; * is a wildcard on the email. (max 200 chars)
tagstringnonOnly contacts with this tag. (max 60 chars)
sourcestringnonHow the contact was added. (one of form, api, import)
afterstringnonSigned up at or after this time. ISO 8601 date or date-time. (max 40 chars)
beforestringnonSigned up before this time. ISO 8601 date or date-time. (max 40 chars)
segment_idstringnonOnly contacts matching this saved segment (seg_…).
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [contacts with tags, engagement, dormant, country], count, total, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
emailstringouiEmail address. (max 320 chars)
namestringnonDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectnonCustom 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[]nonTags to attach, e.g. ["VIP"]. Up to 50. (0–50 items)
list_idsstring[]nonLists to add the contact to (lst_…). (0–100 items)
statusstringnonsubscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed)
consent_basisstringnonHow 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.
Exemple de params 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.

ParamètreTypeObligatoireDescription
emailstringouiEmail address. (max 320 chars)
namestringnonDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectnonCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
tagsstring[]nonTags to add, e.g. ["VIP"]. Existing tags are kept. (0–50 items)
timezonestringnonIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
localestringnonLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
consent_basisstringnonHow 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).
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
contact_idstringouiContact ID (starts with ct_) or the contact's email address. (max 320 chars)
ReturnsThe contact.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
contact_idstringouiContact ID (starts with ct_) or the contact's email address. (max 320 chars)
namestringnonNew display name. (max 200 chars)
fieldsobjectnonCustom 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[]nonReplace all of the contact's tags with these. (0–50 items)
add_tagsstring[]nonTags to add. (0–50 items)
remove_tagsstring[]nonTags to remove. (0–50 items)
statusstringnonOnly unsubscribed is accepted. (one of unsubscribed)
ReturnsThe updated contact.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
contact_idstringouiContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
csvstringouiThe CSV file content, header row first. (max 5242880 chars)
list_idstringnonAdd every accepted row to this list (lst_…).
consent_basisstringouiHow 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[]nonTags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items)
update_existingbooleannonMerge names and fields into contacts that already exist. Their status never changes.
Returns{id, accepted, created, existing, skipped, invalid, errors: [{line, reason}], tags}.
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [imports], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
actionstringouiWhat to do. (one of tag, untag, add_to_list, remove_from_list, unsubscribe, delete)
contact_idsstring[]nonContact IDs (ct_…). Use this or filter. (0–10000 items)
filterobjectnonEveryone matching these list_contacts filters. Use this or contact_ids.
filter.list_idstringnonMembers of this list.
filter.statusstringnonOnly 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.querystringnonEmail or name contains; * is an email wildcard. (max 200 chars)
filter.tagstringnonHas this tag. (max 60 chars)
filter.sourcestringnonHow the contact was added. (one of form, api, import)
filter.afterstringnonSigned up at or after. ISO 8601 date or date-time. (max 40 chars)
filter.beforestringnonSigned up before. ISO 8601 date or date-time. (max 40 chars)
filter.segment_idstringnonMatches this segment.
tagsstring[]nonFor tag and untag. (0–50 items)
list_idstringnonFor add_to_list and remove_from_list (lst_…).
confirm_countintegernonFor 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
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [{tag, count}], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [{key, label, type, createdAt}], count, types, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
field_keystringouiField 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)
labelstringnonLabel shown in the dashboard. Defaults to the key. (max 80 chars)
typestringnontext (default), number, or date. (one of text, number, date)
Returns{key, label, type, createdAt}.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
field_keystringouiField 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)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [{id, name, match, conditions, count}], count, fields, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
segment_idstringouiSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Returns{id, name, match, conditions, count}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
matchstringnonall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]nonUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringouitag, 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[].keystringnonCustom field key when field is field. (max 40 chars)
conditions[].opstringouitag: 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,numbernonRequired 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]}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
namestringouiSegment name. (max 120 chars)
matchstringnonall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]nonUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringouitag, 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[].keystringnonCustom field key when field is field. (max 40 chars)
conditions[].opstringouitag: 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,numbernonRequired 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.
Exemple de params 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.

ParamètreTypeObligatoireDescription
segment_idstringouiSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
namestringnonSegment name. (max 120 chars)
matchstringnonall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]nonUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringouitag, 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[].keystringnonCustom field key when field is field. (max 40 chars)
conditions[].opstringouitag: 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,numbernonRequired 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.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
segment_idstringouiSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [lists], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
namestringouiList name, shown on the signup form. (max 200 chars)
descriptionstringnonShort description shown on the signup form. (max 500 chars)
form_enabledbooleannonPublish the hosted signup form.
form_fromstringnonSender of signup confirmation emails, e.g. Acme <news@example.com>, on a verified domain. (max 320 chars)
redirect_urlstringnonhttps page to open after a signup is confirmed. (max 500 chars)
welcomeobjectnonWelcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledbooleannonSend it.
welcome.subjectstringnonSubject; merge tags allowed. (max 300 chars)
welcome.htmlstringnonHTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstringnonMarkdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobjectnonPublic 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.enabledbooleannonPublish the site.
site.slugstring,nullnonAddress after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,nullnonSite title. Defaults to the list name. (max 120 chars)
site.descriptionstring,nullnonShort description under the title. (max 300 chars)
site.accentstring,nullnonAccent color, e.g. #0a7d4f.
ReturnsThe list.
Exemple de params 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.

ParamètreTypeObligatoireDescription
list_idstringouiList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
ReturnsThe list.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
list_idstringouiList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
namestringnonNew name. (max 200 chars)
descriptionstringnonNew description. (max 500 chars)
form_enabledbooleannonPublish or unpublish the hosted signup form.
form_fromstringnonSender of signup confirmation emails, on a verified domain. (max 320 chars)
redirect_urlstringnonhttps page to open after a signup is confirmed. (max 500 chars)
welcomeobjectnonWelcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledbooleannonSend it.
welcome.subjectstringnonSubject; merge tags allowed. (max 300 chars)
welcome.htmlstringnonHTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstringnonMarkdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobjectnonPublic 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.enabledbooleannonPublish the site.
site.slugstring,nullnonAddress after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,nullnonSite title. Defaults to the list name. (max 120 chars)
site.descriptionstring,nullnonShort description under the title. (max 300 chars)
site.accentstring,nullnonAccent color, e.g. #0a7d4f.
ReturnsThe updated list.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
list_idstringouiList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
list_idstringouiList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idsstring[]nonContact IDs (ct_…). (0–500 items)
emailsstring[]nonContact email addresses. (0–500 items)
Returns{listId, added, notFound, list}.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
list_idstringouiList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idstringouiContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
statusstringnonOnly broadcasts with this status. (one of draft, sending, sent, cancelled, failed)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [broadcasts], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
namestringnonInternal name. Defaults to the subject. (max 200 chars)
list_idstringnonThe list to send to (lst_…).
fromstringnonSender on a verified domain, e.g. Acme <news@example.com>. (max 320 chars)
reply_tostringnonReply-To address. (max 320 chars)
subjectstringnonSubject line; merge tags allowed. (max 998 chars)
preview_textstringnonInbox preview text shown after the subject. (max 300 chars)
htmlstringnonHTML body; merge tags allowed and escaped.
textstringnonPlain-text body; merge tags allowed.
templateobjectnonA published hosted template instead of subject/html/text. Template variables are filled from the contact's name, email, and fields.
template.idstringnon
template.keystringnon
template.version_idstringnon
markdownstringnonMarkdown 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,nullnonBlock 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.
editorstringnonWhich editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobjectnonWho gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,nullnonOnly list members matching this segment (seg_…), or null for the whole list.
audience.orderstringnonWith a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,nullnonSend to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobjectnonOpen and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensbooleannonAdd an open pixel.
tracking.clicksbooleannonRewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobjectnonPublish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledbooleannonPublish it.
web.slugstring,nullnonIssue address; defaults to the subject. (max 100 chars)
web.pinnedbooleannonKeep it at the top of the site.
ReturnsThe draft broadcast.
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe broadcast.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
namestringnonInternal name. (max 200 chars)
list_idstringnonThe list to send to.
fromstringnonSender on a verified domain. (max 320 chars)
reply_tostringnonReply-To address. (max 320 chars)
subjectstringnonObjet. (998 caractères max.)
preview_textstringnonInbox preview text. (max 300 chars)
htmlstringnonCorps HTML.
textstringnonCorps en texte brut.
templateobject,nullnonA published hosted template, or null to remove it.
markdownstringnonMarkdown 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,nullnonBlock 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.
editorstringnonWhich editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobjectnonWho gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,nullnonOnly list members matching this segment (seg_…), or null for the whole list.
audience.orderstringnonWith a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,nullnonSend to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobjectnonOpen and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensbooleannonAdd an open pixel.
tracking.clicksbooleannonRewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobjectnonPublish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledbooleannonPublish it.
web.slugstring,nullnonIssue address; defaults to the subject. (max 100 chars)
web.pinnedbooleannonKeep it at the top of the site.
ReturnsThe updated draft.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
idempotency_keystringnonEn-tête Idempotency-Key (200 caractères max.). Ne la réutilisez que pour réessayer exactement cette requête. (200 caractères max.)
ReturnsThe broadcast with status sending and totals.
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe cancelled broadcast with totals.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
statusstringnonOnly recipients with this outcome. (one of queued, sending, sent, held, skipped, failed)
activitystringnonOnly recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed)
querystringnonRecipient email contains this text. (max 200 chars)
includestringnonlinks adds the links each recipient clicked (implied by activity: clicked). (one of links)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [{contactId, email, status, skipReason, emailId, error, provider, deliveredAt, openedAt, clickedAt, opens, clicks, bouncedAt, complainedAt, unsubscribedAt, links?}], count, totals, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast 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}}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
tostring[]nonTest recipients (up to 5). (1–5 items)
contact_idstringnonFill merge tags from this contact (ct_…). (max 320 chars)
rememberbooleannonSave to as the default test recipients.
Returns{data: [{to, id, status: sent|failed, error?}]}.
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
scheduled_atstringouiWhen 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.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe draft broadcast.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe new draft broadcast.
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
limitintegerouiHow many more people at most. (1–10000000)
idempotency_keystringnonEn-tête Idempotency-Key (200 caractères max.). Ne la réutilisez que pour réessayer exactement cette requête. (200 caractères max.)
Returns{added, broadcast}.
Exemple de params 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.

ParamètreTypeObligatoireDescription
broadcast_idstringouiBroadcast 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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

Aucun paramètre.

Returns{postalAddress, design: {accentColor, font, align}, cleanup: {enabled, afterSends, quietDays, subject, body, from}, testRecipients}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
postal_addressstringnonSender's postal address for the footer. Empty string removes it. (max 300 chars)
designobjectnonRendering design for Markdown and block content.
design.accentColorstring,nullnonHex color like #0a7d4f, or null for the default.
design.fontstringnonFont family. (one of sans, serif, mono)
design.alignstringnonText alignment. (one of left, center)
cleanupobjectnonList cleanup of readers who stopped opening.
cleanup.enabledbooleannonTurn list cleanup on or off.
cleanup.afterSendsintegernonBroadcasts in a row without an open or click (3-50). (3–50)
cleanup.quietDaysintegernonDays without engagement (30-730). (30–730)
cleanup.subjectstring,nullnonSubject of the cleanup email; merge tags allowed. (max 200 chars)
cleanup.bodystring,nullnonBody text of the cleanup email. (max 2000 chars)
cleanup.fromstring,nullnonSender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars)
test_recipientsstring[]nonDefault addresses for send_broadcast_test (up to 5). (0–5 items)
ReturnsThe updated settings.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
daysintegernonWindow 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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [{id, url, width, height, size, filename, createdAt}], pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
emailstringouiThe contact's email address. (max 320 chars)
eventstringouiWhat they did: a lowercase letter, then a-z, 0-9, and _ (e.g. checkout_started). Names starting email. are reserved. (max 64 chars)
propertiesobjectnonUp 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_atstringnonWhen 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_keystringnonStable ID for this event (max 200 chars). A second call with the same key records nothing and returns the first result. (max 200 chars)
contactobjectnonChanges to the contact, applied with the event.
contact.namestringnonDisplay name. (max 200 chars)
contact.fieldsobjectnonCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
contact.timezonestringnonIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
contact.localestringnonLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
contact.consent_basisstringnonHow 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]}.
Exemple de params 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.

ParamètreTypeObligatoireDescription
domainstringnonOnly 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)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation 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}].
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
keystringouiAddress of the automation: 1-63 characters of a-z, 0-9, and - (e.g. checkout-recovery). (max 63 chars)
namestringouiName shown in the dashboard. (max 200 chars)
audience_labelstringnonWho this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstringnonWhat converting means, in a word or two, e.g. paid. (max 80 chars)
entryobjectnonHow 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.typestringouiEntry type. (one of event, bucket, date_field, manual)
entry.eventstringnonEvent name for an event entry, e.g. checkout_started.
entry.segment_idstringnonSegment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstringnonContact field key for a date_field entry. (max 40 chars)
entry.reentrystringnonWhether someone who finished may enter again. (one of never, after_end)
exit_rulesobjectnonWhen 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,nullnonEvent that counts as converting, e.g. payment_completed.
exit_rules.no_goalbooleannonTrue when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]nonEvents that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysintegernonDays before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobjectnonPer-automation settings. Omitted keys keep their value.
settings.exempt_from_holdbooleannonSkip 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,nullnonAt 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,nullnonStored 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_pctnumbernonPercent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysintegernonAn email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysintegernonHow long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positionintegernonPriority. 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_namestringnonSender display name, e.g. Acme. (max 120 chars)
from_addressstringnonSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringnonReply-To address. (max 320 chars)
stepsobject[]nonThe emails, in order. position defaults to the place in this list. (0–50 items)
steps[].positionintegernonPosition of the email in the automation, 1 to 50. (1–50)
steps[].subjectstringnonSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
steps[].preheaderstringnonInbox preview line. (max 300 chars)
steps[].contentobjectnonBlock 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[].htmlstringnonHTML body. The unsubscribe footer is added automatically.
steps[].textstringnonCorps en texte brut.
steps[].editorstringnonHow 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_secondsintegernonWhen 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[]nonMerge 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_windowbooleannonSend 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}].
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
namestringnonName shown in the dashboard. (max 200 chars)
audience_labelstringnonWho this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstringnonWhat converting means, in a word or two, e.g. paid. (max 80 chars)
entryobjectnonHow 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.typestringouiEntry type. (one of event, bucket, date_field, manual)
entry.eventstringnonEvent name for an event entry, e.g. checkout_started.
entry.segment_idstringnonSegment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstringnonContact field key for a date_field entry. (max 40 chars)
entry.reentrystringnonWhether someone who finished may enter again. (one of never, after_end)
exit_rulesobjectnonWhen 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,nullnonEvent that counts as converting, e.g. payment_completed.
exit_rules.no_goalbooleannonTrue when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]nonEvents that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysintegernonDays before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobjectnonPer-automation settings. Omitted keys keep their value.
settings.exempt_from_holdbooleannonSkip 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,nullnonAt 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,nullnonStored 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_pctnumbernonPercent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysintegernonAn email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysintegernonHow long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positionintegernonPriority. 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_namestringnonSender display name, e.g. Acme. (max 120 chars)
from_addressstringnonSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringnonReply-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}].
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerouiPosition of the email in the automation, 1 to 50. (1–50)
templatestringnonId 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)
subjectstringnonSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringnonInbox preview line. (max 300 chars)
contentobjectnonBlock 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.
htmlstringnonHTML body. The unsubscribe footer is added automatically.
textstringnonCorps en texte brut.
editorstringnonHow 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_secondsintegernonWhen 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[]nonMerge 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_windowbooleannonSend 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}.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerouiPosition of the email in the automation, 1 to 50. (1–50)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerouiPosition of the email in the automation, 1 to 50. (1–50)
localestringouiLanguage tag of the version, e.g. fr or pt-br. (max 35 chars)
subjectstringnonSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringnonInbox preview line. (max 300 chars)
contentobjectnonBlock 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.
htmlstringnonHTML body. The unsubscribe footer is added automatically.
textstringnonCorps en texte brut.
Returns{locale, subject, preheader, content, html, text, updated_at}.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
statusstringouion 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}.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerouiPosition of the email in the automation, 1 to 50. (1–50)
localestringnonSend 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)
sampleobjectnonValues 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_runbooleannonSend 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}]}.
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
localestringnonSend 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)
sampleobjectnonValues 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}.
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringouiEmail address of an existing contact. (max 320 chars)
propertiesobjectnonUp 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_atstringnonThe 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}.
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringouiEmail address of the contact. (max 320 chars)
reasonstringnonWhy, 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}.
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
fromstringnonFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringnonLast day of the report as a UTC date (YYYY-MM-DD), inclusive.
domainstringnonOnly 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}]}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
fromstringnonFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringnonLast 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}]}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
didstringnonWhat the people did. Defaults to entered. (one of entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, waiting)
stepintegernonOnly this email of the automation, by its position. (1–50)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
automation_keystringouiAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
contact_idstringouiContact 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}}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

Aucun paramètre.

Returns{max_emails, period_days, min_gap_hours, window_start, window_end, weekdays, default_timezone, product_name, sender_name, updated_at}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
max_emailsintegernonMost automation emails one person may get in period_days. Default 2. (1–50)
period_daysintegernonThe period max_emails applies to, in days. Default 7. (1–90)
min_gap_hoursintegernonLeast time between two automation emails to one person, in hours. Default 44. (0–720)
window_startintegernonFirst hour of the day emails may go out, local time (0-23). Default 9. (0–23)
window_endintegernonHour sending stops, local time (1-24); must be later than window_start. Default 18. (1–24)
weekdaysinteger[]nonDays emails may go out: 0 = Sunday to 6 = Saturday. Default [1, 2, 3, 4, 5]. (1–7 items)
default_timezonestringnonIANA time zone used for contacts that have none, e.g. Europe/London. (max 64 chars)
product_namestringnonYour product's name, for {{ product_name }}. (max 120 chars)
sender_namestringnonWho the emails are from, for {{ sender_name }}. (max 120 chars)
ReturnsThe updated limits.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
template_idstringouiId 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.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
template_idstringouiId 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)
keystringnonAddress 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)
namestringnonName shown in the dashboard. Defaults to the template's own name. (max 200 chars)
from_namestringnonSender display name, e.g. Acme. (max 120 chars)
from_addressstringnonSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringnonReply-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.
Exemple de params 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.

ParamètreTypeObligatoireDescription
contactstringnonOnly this contact: a contact ID or an email address. (max 320 chars)
namestringnonOnly this event, e.g. checkout_started. See list_event_names. (max 64 chars)
fromstringnonEvents from this UTC date (YYYY-MM-DD) or ISO 8601 date-time on. (max 40 chars)
tostringnonEvents up to this UTC date (the whole day) or ISO 8601 date-time. (max 40 chars)
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Returns{data: [{event, words, count}], count, days, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
connection_idstringouiConnection 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}].
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
namestringouiWhat to call it, e.g. Stripe. (max 80 chars)
kindstringouistripe, dodo, or generic. (one of generic, stripe, dodo)
consent_basisstringouiHow 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_prefixstringnonPut in front of every event name, e.g. stripe_. (max 32 chars)
enabledbooleannonDefaults to true. Pass false to create it switched off.
mappingobjectnonFor a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstringnonWhere the contact's email address is. (max 120 chars)
mapping.eventstringnonWhere the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestringnonOne fixed event name, instead of event. (max 64 chars)
mapping.timestringnonWhere the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstringnonWhere a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]nonThe 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.
Exemple de params 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.

ParamètreTypeObligatoireDescription
connection_idstringouiConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
namestringnonA new name. (max 80 chars)
enabledbooleannontrue: record what arrives. false: answer 404 and record nothing.
consent_basisstringnonHow 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_prefixstringnonPut in front of every event name, e.g. stripe_. (max 32 chars)
mappingobjectnonFor a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstringnonWhere the contact's email address is. (max 120 chars)
mapping.eventstringnonWhere the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestringnonOne fixed event name, instead of event. (max 64 chars)
mapping.timestringnonWhere the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstringnonWhere a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]nonThe 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}.
AnnotationsidempotentHint
Exemple de params 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.

ParamètreTypeObligatoireDescription
connection_idstringouiConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
Renvoie{ok: true}.
AnnotationsdestructiveHint idempotentHint
Exemple de params tools/call
{
  "name": "delete_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}

Compte, utilisation, statistiques et clés

Lecture seuleget_account
GET /account

Obtenir le compte, l’utilisation et la facturation

Adresse e-mail du propriétaire du compte, formule/palier d’accès, livraisons par destinataire utilisées sur la période en cours par rapport au quota, domaines utilisés par rapport à la limite, transfert de pièces jointes, résumé de réputation, état de l’abonnement, formules publiées et compteurs de l’espace de travail. À utiliser pour vérifier le quota restant ou le destinataire autorisé pendant l’essai (l’adresse e-mail du compte).

Aucun paramètre.

Renvoie{user: {email, …}, usage: {domainsUsed, domainLimit, recipientDeliveries, emailQuotaMonth, attachmentBytes, attachmentByteLimit, periodKey}, access: {tier, planCode}, reputation, infrastructure, billing: {status, subscriptions, …}, plans, workspace: {mailer, stats}}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params 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.

Aucun paramètre.

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}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_account_diagnostics",
  "arguments": {}
}
Lecture seuleget_analytics
GET /analytics

Obtenir les statistiques d’envoi

Statistiques du tableau de bord sur les 7, 30 ou 90 derniers jours : totaux envoyés/reçus/délivrés/bounces/bloqués/ouverts/cliqués/plaintes, chronologie quotidienne, principaux domaines d’envoi et principaux objets.

ParamètreTypeObligatoireDescription
daysintegernonFenêtre en jours : 7, 30 (par défaut) ou 90. (valeurs possibles : 7, 30, 90)
Renvoie{window, days, metrics, timeline: [{day, sent, received}], domains, topContent}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}
Lecture seulelist_api_keys
GET /keys

Lister les métadonnées des clés API

Liste les noms des clés API, leurs préfixes non secrets et leurs dates de dernière utilisation. Lecture seule : ce serveur MCP ne peut ni créer, ni faire tourner, ni révoquer de clés ; c’est un humain qui s’en charge dans le tableau de bord. Paginé : le résultat inclut pagination {offset, limit, returned, total?, has_more, next_offset}.

ParamètreTypeObligatoireDescription
limitintegernonTaille de page. 50 par défaut. (par défaut 50 ; 1–200)
offsetintegernonNombre d’enregistrements à ignorer. Utilisez pagination.next_offset de la page précédente. (par défaut 0 ; 0–…)
Renvoie{data: [{id, name, prefix, lastUsedAt, createdAt}], count, pagination}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "list_api_keys",
  "arguments": {}
}
Lecture seuleget_service_health
GET /health

Vérifier l’état du service SendHQ

Vérifie que l’API SendHQ est opérationnelle et indique quel fournisseur de messagerie est actif. Ne nécessite pas de clé API valide.

Aucun paramètre.

Renvoie{ok, service, mailer}.
AnnotationsreadOnlyHint idempotentHint
Exemple de params tools/call
{
  "name": "get_service_health",
  "arguments": {}
}

Inventaire de couverture de l’API

Chaque opération de l’API publique et l’outil qui la couvre. Tout ce qu’un utilisateur peut faire dans le tableau de bord et qui dispose d’une API est couvert ; les exclusions ci-dessous sont délibérées.

EndpointOutilRemarques
POST /emailssend_emailEnvoyer un e-mail
POST /emails/batchsend_batchEnvoyer jusqu’à 100 messages personnalisés
GET /emailslist_emailsLister les e-mails envoyés et reçus
GET /emails/:idget_emailRécupérer un e-mail et ses pièces jointes
PATCH /emails/:idmark_emailModifier l’état lu, l’archivage, le spam, la catégorie ou l’importance
POST /emails/:id/labelslabel_emailAjouter ou retirer des libellés sur un e-mail
DELETE /emails/:iddelete_emailSupprimer un e-mail conservé
GET /emails/:id/eventslist_email_eventsLister les événements de livraison d’un e-mail
GET /threads/:idget_threadRécupérer une conversation dans l’ordre chronologique
GET /labelslist_labelsLister les libellés avec leur nombre de messages et leurs règles de classement
POST /labelscreate_labelCréer un libellé, avec des règles de classement automatique en option
GET /labels/:idget_labelRécupérer un libellé par identifiant ou par nom
PATCH /labels/:idupdate_labelRenommer un libellé, changer sa couleur ou le transformer en catégorie
DELETE /labels/:iddelete_labelSupprimer un libellé sans supprimer ses e-mails
POST /labels/:id/rulescreate_label_ruleAjouter une règle de classement automatique à un libellé
DELETE /labels/:id/rules/:rule_iddelete_label_ruleSupprimer une règle de classement automatique
POST /draftscreate_draftCréer un brouillon de rédaction
GET /draftslist_draftsLister les brouillons de rédaction
GET /drafts/:idget_draftRécupérer un brouillon et ses pièces jointes
PUT /drafts/:idupdate_draftRemplacer le contenu d’un brouillon
DELETE /drafts/:iddelete_draftAbandonner un brouillon
POST /drafts/:id/attachmentsupload_attachmentTéléverser une pièce jointe dans un brouillon
GET /attachments/:iddownload_attachmentTélécharger une pièce jointe privée
DELETE /attachments/:iddelete_attachmentSupprimer une pièce jointe privée
GET /sending-identitieslist_sending_identitiesLister les identités d’expéditeur vérifiées
GET /templateslist_templatesLister les modèles hébergés
POST /templatescreate_templateCréer un modèle hébergé
GET /templates/:idget_templateRécupérer les brouillons, les versions publiées et l’utilisation
PUT /templates/:id/draftupdate_template_draftEnregistrer automatiquement un brouillon de modèle
POST /templates/:id/draftcreate_template_draftCréer un nouveau brouillon à partir de la version publiée
POST /templates/:id/renderrender_templateObtenir le rendu exact produit par le serveur
POST /templates/:id/testsend_template_testEnvoyer un instantané de test
POST /templates/:id/publishpublish_templatePublier une version immuable du modèle
POST /templates/:id/archivearchive_templateArchiver un modèle
POST /templates/:id/restorerestore_templateRestaurer un modèle archivé
POST /domainsadd_domainAjouter un domaine d’envoi
GET /domainslist_domainsLister les domaines et l’état DNS en cache
GET /domains/:idget_domainRécupérer les détails de configuration d’un domaine
POST /domains/:id/verifyverify_domainRefresh domain and DNS verification
POST /domains/:id/inbound/setupsetup_inboundProvision inbound receiving
POST /domains/:id/inbound/verifyverify_inboundVérifier le routage MX entrant
DELETE /domains/:iddelete_domainSupprimer un domaine
GET /dns/providerget_dns_providerDétecter le fournisseur DNS faisant autorité et les hôtes relatifs des enregistrements
GET /dns/domain-connect/connectget_domain_connect_linkCréer un lien de consentement Domain Connect pour configurer le DNS en un clic
POST /inboxescreate_inboxCréer une adresse de réception
GET /inboxeslist_inboxesLister les adresses de réception
GET /inboxes/:idget_inboxRécupérer une adresse de réception
PATCH /inboxes/:idupdate_inboxRenommer, activer ou désactiver une boîte de réception
PUT /inboxes/:id/forwardingset_inbox_forwardingTransférer le courrier reçu par une boîte de réception vers une autre adresse
DELETE /inboxes/:iddelete_inboxSupprimer une boîte de réception en conservant les messages
GET /deliverability/statsdeliverability_statsRécupérer les statistiques de livraison sur 30 jours
GET /deliverability/reputationlist_sender_reputationLister l’état de réputation par identité d’expéditeur exacte
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_suppressionsLister les suppressions de l’espace de travail
DELETE /suppressions/:emailremove_suppressionRetirer une suppression pour bounce éligible
GET /blocked-recipientslist_blocked_recipientsLister les bounces, les plaintes et les désinscriptions
GET /webhooksnon exposéWebhook 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 exposéWebhook 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 exposéWebhook 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 exposéWebhook 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 exposéWebhook 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 exposéWebhook 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 exposéWebhook 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 exposéWebhook 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 exposéWebhook 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 exposéWebhook 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 exposéImage 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 exposéImage 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 exposéHistory 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 exposéHistory 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 exposéThese 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 exposéThese 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 exposéThe 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_accountRécupérer le compte, l’utilisation, l’état de facturation et les compteurs de l’espace de travail avec une clé API
GET /account/diagnosticsget_account_diagnosticsDiagnose sending and receiving problems in the workspace
GET /analyticsget_analyticsRécupérer les statistiques d’envoi du tableau de bord sur 7, 30 ou 90 jours
GET /profileget_accountÉquivalent réservé aux sessions de GET /account ; le serveur MCP lit la route par clé API.
POST /billing/checkoutnon exposéLes modifications de facturation sont par conception réservées aux sessions et exigent la présence du propriétaire du compte dans le tableau de bord. L’état de facturation peut être lu avec get_account.
POST /billing/cancelnon exposéLes modifications de facturation sont par conception réservées aux sessions et exigent la présence du propriétaire du compte dans le tableau de bord. L’état de facturation peut être lu avec get_account.
POST /keysnon exposéExclu délibérément : un agent ne doit ni émettre ni détruire d’identifiants. Les clés sont gérées par un humain dans le tableau de bord.
GET /keyslist_api_keysLister les métadonnées des clés API
DELETE /keys/:idnon exposéExclu délibérément : un agent ne doit ni émettre ni détruire d’identifiants. Les clés sont gérées par un humain dans le tableau de bord.

Délibérément non disponible

FonctionnalitéEndpointsRaison
Créer, faire tourner, révoquer ou supprimer des clés APIPOST /keys, DELETE /keys/:idExclu délibérément : un agent ne doit ni émettre ni détruire d’identifiants. Les clés sont gérées par un humain dans le tableau de bord.
Lancer un paiement ou résilier un abonnementPOST /billing/checkout, POST /billing/cancelLes modifications de facturation sont par conception réservées aux sessions et exigent la présence du propriétaire du compte dans le tableau de bord. L’état de facturation peut être lu avec get_account.
DNS en un clic Cloudflare (OAuth)GET /api/dns/cloudflare/connectNécessite une session de navigateur interactive et un consentement OAuth Cloudflare. Utilisez plutôt les enregistrements de get_domain, les hôtes de get_dns_provider ou get_domain_connect_link.
Inscription, connexion, déconnexion, association d’un compte Google/api/auth/*Authentification humaine dans le navigateur ; le serveur MCP s’authentifie avec une clé API.
Formulaire de contact du supportPOST /api/contactFormulaire public du site marketing destiné aux humains, pas une opération sur l’espace de travail.
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.

Catalogue lisible par machine : /docs/mcp/tools.json (schémas, annotations, correspondance des endpoints, exclusions). Version Markdown de cette page : /docs/mcp.md. Si la CLI est installée, sendhq commands --format json affiche le même catalogue.