Für KI-Agenten

SendHQ MCP-Server

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
Installieren und verbinden (Claude Code)
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
claude mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp

Was dieser Server ist

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.

Es ist ein lokaler stdio-Server, der in die sendhq-CLI-Binärdatei eingebaut ist. Ihr MCP-Client startet sendhq mcp als Kindprozess und spricht JSON-RPC über stdin/stdout. Jeder Tool-Aufruf wird zu genau einer dokumentierten Anfrage an die SendHQ REST API unter https://sendhq.cc/api/v1, authentifiziert mit dem API-Schlüssel Ihres Workspace. Der MCP-Server hat also genau die Berechtigungen dieses Schlüssels und keine weiteren.

  • 142 tools in 10 groups, generated from one catalog that is also published as tools.json.
  • Strikte JSON Schemas: Unbekannte Argumente, falsche Typen und fehlende Pflichtfelder werden lokal abgelehnt, bevor etwas SendHQ erreicht.
  • Strukturierte Fehler mit stabilem code, dem HTTP-status, einer explanation, einem konkreten remedy und der Angabe, ob ein erneuter Versuch helfen kann.
  • Jedes Tool, das echte E-Mails sendet oder Daten löscht, sagt das gleich in den ersten Worten seiner Beschreibung und trägt MCP-Sicherheitsannotationen.
  • Der --read-only-Modus blendet alle sendenden und ändernden Tools aus.
  • Es wird nichts protokolliert. stdout enthält nur Protokollnachrichten; der API-Schlüssel und der Nachrichteninhalt gelangen nie in ein Log.
Nicht der MCP-Endpunkt für die Dokumentation.SendHQ betreibt außerdem einen kleinen, nur lesenden MCP-Endpunkt für die Dokumentation unter https://sendhq.cc/api/mcp (Preis- und Doku-Abfragen, kein Kontozugriff). Der Server auf dieser Seite ist der vollständige, kontobezogene; er läuft lokal oder als gehosteter Connector weiter unten.

Use SendHQ in Claude, ChatGPT and Grok

Keine Installation nötig: SendHQ betreibt diesen Server auch als gehosteten Connector unter https://mcp.sendhq.cc/mcp mit denselben Tools. Sie melden sich mit Ihrem SendHQ-Konto an, statt einen Schlüssel einzufügen.

Claude

  1. Öffnen Sie Settings → Connectors und suchen Sie SendHQ im Verzeichnis, oder wählen Sie Add custom connector und fügen Sie https://mcp.sendhq.cc/mcp ein.
  2. Klicken Sie auf Connect, melden Sie sich bei SendHQ an, prüfen Sie den Zugriff und klicken Sie auf Allow.
  3. Bitten Sie Claude, Ihren Posteingang zu prüfen, eine E-Mail von Ihrer verifizierten Domain zu senden oder einen Bounce zu erklären.

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.

Freigabe und Trennen

  • The request_feature tool sends a feature request to the SendHQ team with your account details, so we can follow up by email.
  • Tools, die echte E-Mails senden oder Daten löschen, sind entsprechend gekennzeichnet. Ob der Assistent vorher nachfragt, legen Sie pro Tool im Assistenten fest: In Claude wählen Sie für diese Tools unter Settings → Connectors → SendHQ die Option Needs approval.
  • Der Connector erhält einen eigenen API-Schlüssel, der nach dem Assistenten benannt ist (zum Beispiel „Claude (AI connector)“). Löschen Sie ihn unter API Keys, um die Verbindung sofort zu trennen.
  • Er kann weder API-Schlüssel erstellen oder widerrufen noch die Abrechnung ändern. Anhänge werden als Base64 gesendet und zurückgegeben; es gibt keinen lokalen Dateizugriff.
  • Sending requires an active subscription. There is no free allowance, including mail to the account owner.

Fragen: postmaster@sendhq.cc. Datenschutz: sendhq.cc/privacy.

Installation

Installieren Sie die sendhq-Binärdatei (Linux, macOS und Windows auf x86-64 und arm64). Das Installationsprogramm prüft die Prüfsumme des Releases und legt die Binärdatei standardmäßig in ~/.local/bin ab.

macOS und Linux
curl -fsSL https://downloads.sendhq.cc/install.sh | sh
Windows PowerShell
irm https://downloads.sendhq.cc/install.ps1 | iex
Installation prüfen
sendhq version
SENDHQ_API_KEY=re_your_key sendhq doctor

Erstellen Sie im Dashboard unter https://sendhq.cc/app#/keys einen API-Schlüssel. Der MCP-Server kann keine Schlüssel erstellen. Der eine Befehl, der den Server startet, lautet:

Den stdio-Server starten
SENDHQ_API_KEY=re_your_key sendhq mcp

Sie führen das normalerweise nie selbst aus: Der MCP-Client startet den Server. Im Terminal ausgeführt, wartet er auf stdin auf JSON-RPC.

Client konfigurieren

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

Fügen Sie --scope user hinzu, damit der Server in jedem Projekt verfügbar ist, oder --scope project, um ihn in die .mcp.json des Projekts zu schreiben. Verweisen Sie in einer gemeinsam genutzten .mcp.json auf den Schlüssel in der Umgebung, statt ihn einzuchecken; Claude Code expandiert ${VAR} in .mcp.json.

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

OpenAI Codex

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

Oder über die Kommandozeile: codex mcp add sendhq --env SENDHQ_API_KEY=re_your_key -- sendhq mcp.

Claude Desktop

Bearbeiten Sie claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) und starten Sie die App neu. Desktop-Apps erben nicht den PATH Ihrer Shell, verwenden Sie daher den absoluten Pfad der Binärdatei (which sendhq).

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

Jeder andere MCP-Client

Konfigurieren Sie einen stdio-Server mit dem Befehl sendhq, den Argumenten ["mcp"] (optional "--read-only") und den unten genannten Umgebungsvariablen. Der Server unterstützt die MCP-Protokollversionen 2024-11-05, 2025-03-26, 2025-06-18 und 2025-11-25 und implementiert initialize, ping, tools/list und tools/call. Tool-Ergebnisse enthalten sowohl einen JSON-Textblock als auch structuredContent.

Roher stdio-Smoke-Test (per Pipe an 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":{}}}

Für den kontobezogenen Server gibt es keinen gehosteten HTTP-Transport. Ein entfernter, schreibfähiger MCP-Endpunkt würde OAuth pro Nutzer erfordern, das SendHQ nicht anbietet; die lokale Binärdatei hält den Schlüssel auf dem Rechner, der ihn ohnehin besitzt.

Umgebung und Flags

Variable oder FlagErforderlichBedeutung
SENDHQ_API_KEYjaAPI-Schlüssel des Workspace (re_…). Jedes Tool außer get_service_health benötigt ihn. Ohne ihn startet der Server trotzdem, und jeder Aufruf liefert einen strukturierten auth_error mit der Anleitung zur Behebung.
SENDHQ_API_BASE_URLneinBasis-URL der API. Standard: https://sendhq.cc/api/v1. Nutzen Sie sie nur für ein lokales oder Staging-Deployment. SENDHQ_BASE_URL wird als älterer Alias akzeptiert.
SENDHQ_MCP_READ_ONLYnein1, true oder yes verhält sich wie --read-only.
--read-onlyneinStellt nur Tools bereit, die weder E-Mails senden noch Zustand ändern. Ausgeblendete Tools werden auch dann abgelehnt, wenn sie per Namen aufgerufen werden.
SENDHQ_PROFILE / --profileneinVerwendet einen mit sendhq auth login im Schlüsselbund des Betriebssystems gespeicherten Schlüssel statt SENDHQ_API_KEY. Die Umgebungsvariable hat Vorrang, wenn beide vorhanden sind.

Der Schlüssel wird nur als Authorization: Bearer-Header an die konfigurierte Basis-URL gesendet. Er wird nie ausgegeben, protokolliert, in Fehlern wiederholt oder in Tool-Ergebnisse aufgenommen.

Sicherheitsmodell für Agenten

  • 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.
  • Ändert den Zustand. Das Erstellen oder Aktualisieren von Entwürfen, Templates, Domains und Postfächern, das Veröffentlichen von Templates und das Starten der Verifizierung verändern den Workspace, senden aber keine E-Mails.
  • Nur lesend. Alles andere ist readOnlyHint: true und kann bedenkenlos aufgerufen werden.
  • Dieser Server ändert nie das DNS. add_domain gibt Einträge zurück, die ein Mensch veröffentlichen muss; get_domain_connect_link gibt eine Zustimmungs-URL zurück, die eine Person öffnen und bei ihrem DNS-Provider bestätigen muss.
  • Dieser Server ändert nie die Abrechnung. get_account liest nur Tarif, Nutzung und Abostatus.
  • 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).
  • Wechseln Sie nicht auf eine andere Absenderadresse, um eine 423-Pause zu umgehen, und fügen Sie abgemeldete oder beschwerdeführende Empfänger nie wieder hinzu.

API-Schlüssel sind ausgeschlossen

Es gibt bewusst keine Tools, die API-Schlüssel erstellen, ändern, rotieren, widerrufen oder löschen. Ein Agent darf keine Zugangsdaten erzeugen oder vernichten. list_api_keys gibt nur Namen, nicht geheime Präfixe und Zeitpunkte der letzten Nutzung zurück. Die Schlüsselverwaltung bleibt im Dashboard bei einem angemeldeten Menschen.

Workflows

1. Erster Versand

  1. get_service_health bestätigt, dass die API erreichbar ist (funktioniert ohne Schlüssel).
  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 listet die nutzbaren Absenderadressen auf. Ist die Liste leer, führen Sie zuerst den Domain-Workflow aus.
  4. Bestätigen Sie Absender, Empfänger, Betreff und Text mit dem Nutzer und rufen Sie dann send_email mit einem idempotency_key auf.
  5. list_email_events mit der zurückgegebenen id zeigt delivery, bounce, complaint oder reject, sobald der Provider es meldet (meist nach Sekunden bis Minuten).
Erster Versand
{
  "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. Domain-Verifizierung von Anfang bis Ende

  1. add_domain with name: "example.com". The result includes the DNS records (DKIM CNAMEs, domain verification, SPF, recommended DMARC).
  2. get_dns_provider mit der domain_id erkennt den maßgeblichen DNS-Provider und liefert für jeden Eintrag den exakten relativen Host, der bei diesem Provider einzutragen ist.
  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. Sobald status den Wert verified hat, erscheinen die Adressen der Domain in list_sending_identities.

3. Bounces, Beschwerden und Sperrliste

  1. list_blocked_recipients gibt jede blockierte Adresse mit Grund (bounce, complaint, unsubscribe) und einer zusammenfassenden Anzahl zurück.
  2. list_suppressions gibt Sperrlisteneinträge für Hard Bounces und Beschwerden zurück; deliverability_stats liefert die Zustell-, Bounce- und Beschwerderaten der letzten 30 Tage; list_sender_reputation zeigt, welche Absenderadressen gedrosselt oder pausiert sind.
  3. Ein Versand mit einem gesperrten Empfänger schlägt mit 422 recipient_suppressed fehl. Entfernen Sie diesen Empfänger und senden Sie erneut.
  4. Rufen Sie remove_suppression nur auf, wenn ein Mensch bestätigt, dass ein zuvor gebouncetes Postfach jetzt funktioniert. Sperren wegen Beschwerden sind dauerhaft (409 complaint_suppression_locked).

4. Eingehende E-Mails empfangen

  1. Die Domain (oft eine Subdomain wie inbound.example.com) muss verifiziert sein.
  2. setup_inbound richtet den Empfang ein und gibt einen MX-Eintrag zurück. Ein Mensch veröffentlicht ihn.
  3. Rufen Sie verify_inbound auf, bis status den Wert ready hat.
  4. create_inbox mit domain_id und local_part (zum Beispiel support) erstellt support@inbound.example.com.
  5. Fragen Sie list_emails mit direction: "in" und unread: true (optional inbox_id) regelmäßig ab. Lesen Sie eine Nachricht mit get_email, die Unterhaltung mit get_thread, Anhänge mit download_attachment und markieren Sie sie mit mark_email (read: true) als erledigt.
  6. Antworten Sie im Thread mit send_email und reply_to_email_id; SendHQ setzt In-Reply-To, References und den Thread.

5. Webhooks und Event-Benachrichtigungen

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. Einen Zustellfehler diagnostizieren

  1. Finden Sie die Nachricht: list_emails mit direction: "out" und to oder query, oder get_email, wenn Sie die ID haben. status: failed bedeutet, dass SendHQ oder der Provider die Nachricht bei der Einlieferung abgelehnt hat; der Fehler der E-Mail nennt den Grund.
  2. list_email_events: bounce (permanent oder vorübergehend, mit der Diagnose des Providers), complaint, reject oder delivery. Noch keine Events bedeutet, dass der Provider noch nichts gemeldet hat; warten Sie und prüfen Sie erneut.
  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 prüft, ob DKIM, SPF und DMARC weiterhin veröffentlicht sind; deliverability_stats zeigt, ob das Problem eine einzelne Nachricht oder ein Trend ist.
  5. Berichten Sie, was die Belege zeigen. Ein delivery-Event bedeutet, dass der Server des Empfängers die Nachricht angenommen hat, nicht dass sie im Posteingang gelandet ist oder gelesen wurde.

7. Einen Aufgaben-Bucket führen (Labels)

  1. create_label mit name (zum Beispiel Agent/Orders) und skip_inbox: true. Das macht das Label zu einem Bucket: Empfangene E-Mails, die es erhalten, werden archiviert und erscheinen nur im Label, nie im Posteingang des Menschen.
  2. Senden Sie Aufgaben-E-Mails mit send_email (oder send_batch) und labels: ["Agent/Orders"]. Antworten auf diese Unterhaltung erben das Label automatisch und umgehen den Posteingang.
  3. Für E-Mails, die außerhalb Ihrer Unterhaltungen beginnen, fügen Sie eine Ablageregel hinzu: create_label_rule mit inbox_id (eine dedizierte Adresse wie orders@…), from, to oder subject. Übergeben Sie apply_to_existing: true, um bereits empfangene E-Mails abzulegen.
  4. Den Bucket abarbeiten: list_emails mit label: "Agent/Orders", direction: "in" und unread: true; lesen Sie mit get_email oder get_thread, antworten Sie mit send_email und reply_to_email_id und setzen Sie nach der Bearbeitung mark_email read: true.
  5. Verschieben Sie eine verirrte Nachricht mit label_email (add / remove) in den Bucket oder heraus. Wenn Sie einer empfangenen Nachricht ein Bucket-Label hinzufügen, wird sie ebenfalls archiviert.
  6. Optional sendet set_inbox_forwarding eine Kopie von allem, was eine Empfangsadresse erhält, an ein anderes Postfach (das Ziel bestätigt zuvor per E-Mail).
In einen Bucket senden
{
  "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. Anhänge und Templates

Hängen Sie mit send_email attachments bis zu 10 Dateien an (jede braucht content_base64 oder einen lokalen file_path; filename entspricht standardmäßig dem Basisnamen der Datei), in einem kostenpflichtigen Tarif. Für gehostete Templates: create_template → update_template_draft → render_template für die Vorschau mit Beispieldaten → send_template_test (sendet eine echte Test-E-Mail) → publish_template. Senden Sie danach mit send_email oder send_batch unter Verwendung von template: {key, data} und genau einem to-Empfänger.

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>"
  }
}

Ergebnisse, Paginierung und Fehler

Ein erfolgreicher Aufruf gibt das JSON-Objekt der API als structuredContent und als JSON-Textblock zurück. Jedes list_*-Tool akzeptiert limit (1–200, Standard 50) und offset und fügt ein pagination-Objekt hinzu. Rufen Sie weiter mit offset: pagination.next_offset auf, solange has_more true ist.

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

Ein fehlgeschlagener Aufruf gibt isError: true mit einem strukturierten Fehler zurück. Befolgen Sie remedy, statt blind zu wiederholen; versuchen Sie es nur erneut, wenn retryable true ist.

Strukturierter Tool-Fehler
{
  "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."
  }
}

Optionale Fehlerfelder: request_id (nennen Sie sie dem Support), retry_after_seconds, problems (Liste der Schema-Verstöße bei invalid_arguments) und idempotent_replayed (siehe Idempotenz).

Idempotenz

send_email und send_batch akzeptieren idempotency_key (max. 200 Zeichen), der als Idempotency-Key-Header gesendet wird. Erzeugen Sie pro logischer Nachricht einen stabilen Schlüssel, zum Beispiel invoice-4812-receipt.

  • Ein Wiederholungsversuch muss denselben Schlüssel UND einen identischen Anfrage-Body verwenden. Derselbe Schlüssel mit irgendeiner Änderung (Empfänger, Betreff, Text, Header, Template-Daten, sogar Argumentwerte) liefert 409 idempotency_conflict.
  • Gleicher Schlüssel, gleicher Body, Original abgeschlossen: SendHQ gibt das gespeicherte Ergebnis zurück, ohne erneut zu senden. So wiederholen Sie nach einem Timeout oder network_error sicher.
  • Gleicher Schlüssel, solange das Original noch läuft: 409 idempotency_in_progress, nach kurzer Wartezeit wiederholbar.
  • Eine neue logische Nachricht braucht einen neuen Schlüssel.
  • Auch gespeicherte Fehler werden wiedergegeben. Ist der erste Versuch fehlgeschlagen, liefert ein Wiederholungsversuch mit demselben Schlüssel genau diesen Fehler mit idempotent_replayed: true und retryable: false. Prüfen Sie mit list_emails (direction: out), dass nichts versendet wurde, beheben Sie die Ursache und senden Sie dann mit einem neuen Schlüssel.
  • Der Server wiederholt nie von sich aus einen POST. Nur lesende GET-Aufrufe werden automatisch wiederholt (bis zu 3 Versuche bei Netzwerkfehlern, 429 und 5xx).
  • send_email mit Inline-attachments kann keinen idempotency_key annehmen, da es mehrere Anfragen ausführt. Für wiederholungssichere Versände mit Anhang: create_draft → upload_attachment → send_email mit draft_id und idempotency_key.
Wiederholungssicherer Versand (bei Timeout exakt wiederholen)
{
  "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"
  }
}

Rate-Limits und Kontingente

SendHQ veröffentlicht kein festes Limit für Anfragen pro Sekunde an die API. Die Grenzen, auf die ein Agent tatsächlich stößt, sind Nutzungslimits, die als 429 zurückgegeben werden:

  • Monatliche Empfängerzustellungen pro Tarif. Jede To-, Cc- und Bcc-Adresse zählt als eine Zustellung. Siehe get_account → usage.recipientDeliveries im Vergleich zu usage.emailQuotaMonth.
  • Tägliche Empfänger pro exakter Absenderadresse, bestimmt durch den Reputationsstatus dieses Absenders (list_sender_reputation → dailyLimit, in bezahlten Tarifen standardmäßig 2.000).
  • 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.
  • Anhänge: höchstens 10 Dateien und 10 MB pro Nachricht; 10 GB empfängergewichteter Anhangstransfer pro Monat in bezahlten Tarifen.
  • Pro Anfrage: To + Cc + Bcc bis zu 100 Adressen; send_batch bis zu 100 Nachrichten.
  • Reputations-Schutzschalter: Überschreiten Bounces oder Beschwerden in einem gleitenden 7-Tage-Fenster den Schwellenwert, wird eine Absenderadresse gedrosselt oder pausiert (423 sender_paused). Sie erholt sich automatisch, sobald die Raten sinken.

quota_exhausted ist nicht wiederholbar, bis die Periode zurückgesetzt wird oder sich der Tarif ändert. rate_limited ist nach retry_after_seconds wiederholbar; wiederholen Sie Versände mit demselben idempotency_key und identischem Body.

Fehlerkatalog

code ist stabil; verzweigen Sie danach und nicht anhand von message.

codeHTTPWiederholen?Bedeutung und empfohlenes Vorgehen
invalid_arguments—neinDie Argumente haben das JSON Schema des Tools lokal nicht bestanden; nichts hat SendHQ erreicht. Korrigieren Sie die in problems aufgeführten Felder.
auth_error401neinAPI-Schlüssel fehlt, wurde widerrufen oder ist falsch. Setzen Sie SENDHQ_API_KEY für den Serverprozess; Schlüssel erstellt ein Mensch im Dashboard.
subscription_required402neinNo active subscription. Nothing is sent, including to the account owner. The owner chooses a plan. Do not retry until then.
payment_required402neinDie Funktion erfordert einen bezahlten Tarif (zum Beispiel Anhänge). Senden Sie ohne sie oder wechseln Sie den Tarif.
sender_domain_not_owned403neinDie Absenderdomain gehört nicht zu diesem Workspace. Nutzen Sie list_sending_identities oder add_domain.
sender_domain_unverified403neinDie Absenderdomain ist noch nicht verifiziert. get_domain, fehlende Einträge veröffentlichen, verify_domain.
domain_limit_reached403neinDas Domain-Limit des Tarifs ist erreicht. Entfernen Sie (mit Freigabe) eine ungenutzte Domain oder wechseln Sie den Tarif.
marketing_not_enabled403neinDie Klasse Marketing ist für diese Domain oder diesen Tarif nicht aktiviert. Verwenden Sie transactional nur, wenn die Nachricht tatsächlich transaktional ist.
forbidden403neinDie Richtlinie erlaubt den Vorgang nicht. Passen Sie die Anfrage an.
not_found404neinDie ID gehört nicht zu diesem Workspace. Listen Sie die Ressource auf, um die richtige ID zu finden; stellen Sie archivierte Templates zuerst wieder her.
idempotency_conflict409neinSchlüssel wurde mit einem anderen Body wiederverwendet. Senden Sie das exakte Original erneut oder verwenden Sie für eine neue Nachricht einen neuen Schlüssel.
idempotency_in_progress409jaDie ursprüngliche Anfrage läuft noch. Warten Sie und wiederholen Sie dann mit demselben Schlüssel und Body.
revision_conflict409neinDer Template-Entwurf hat sich geändert, seit Sie ihn gelesen haben. get_template, zusammenführen, erneut speichern.
complaint_suppression_locked409neinDer Empfänger hat sich beschwert. Schreiben Sie ihm nie wieder.
inbound_not_ready409neinInbound-Empfang ist nicht bereit. setup_inbound, MX veröffentlichen, verify_inbound.
conflict409neinDie Ressource existiert bereits oder befindet sich im falschen Zustand. Lesen Sie sie aus und passen Sie an.
attachments_too_large413neinMehr als 10 Dateien oder 10 MB. Entfernen Sie Anhänge oder verkleinern Sie sie.
recipient_suppressed422neinEin Empfänger hat zuvor gebounct oder sich beschwert. Entfernen Sie ihn; siehe list_blocked_recipients.
recipient_unsubscribed422neinEin Empfänger hat sich von Marketing-E-Mails abgemeldet. Entfernen Sie ihn dauerhaft.
validation_failed422neinInhalt abgelehnt, zum Beispiel Template-Daten, die den Variablenvertrag verletzen. Korrigieren Sie die Eingabe.
sender_paused423neinDiese Absenderadresse wurde vom 7-Tage-Schutzschalter für Bounces/Beschwerden pausiert. Stoppen Sie, bereinigen Sie die Liste und warten Sie auf die automatische Erholung.
account_paused423neinWorkspace 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_exhausted429neinMonthly 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_limited429jaSlow down; wait retry_after_seconds. This is not a daily, hourly, or Gmail cap.
server_error5xxjaVorübergehender Fehler bei SendHQ oder beim Provider. Warten Sie mit Backoff und wiederholen Sie; bei Versänden mit demselben Schlüssel und Body. Ist idempotent_replayed true, verwenden Sie einen neuen Schlüssel, nachdem Sie bestätigt haben, dass nichts gesendet wurde.
network_error—jaAnfrage oder Antwort ging verloren. Wiederholen Sie; bei Versänden macht derselbe idempotency_key das sicher.
invalid_request400neinFehlerhafte Anfrage. Lesen Sie message und korrigieren Sie sie.
tool_error—neinLokaler Fehler im MCP-Server (zum Beispiel ein nicht lesbarer file_path). Lesen Sie message.

Tool-Referenz

Jedes Tool mit Sicherheitsklasse, dem aufgerufenen REST-Endpunkt, seinen Parametern, dem Rückgabeformat und einem Beispiel für das tools/call-params-Objekt. Die Parameter sind exakt: Der Server lehnt alles ab, was nicht aufgeführt ist.

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 und Threads

Sendet echte E-Mailssend_email
POST /emails

Eine E-Mail senden

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.

Geben Sie mindestens eines an: html, text, template.

ParameterTypErforderlichBeschreibung
fromstringjaAbsender, z. B. Acme <hello@example.com>. Die Domain muss in diesem Workspace verifiziert sein (siehe list_sending_identities). (max. 998 Zeichen)
tostring[]jaEmpfänger. Jeder Eintrag ist eine Adresse, optional mit Anzeigenamen. To+cc+bcc dürfen zusammen höchstens 100 ergeben; jedes Ziel verbraucht ein Zustellkontingent. (1–100 Einträge)
ccstring[]neinEmpfänger in Kopie (Cc). (0–100 Einträge)
bccstring[]neinEmpfänger in Blindkopie (Bcc). (0–100 Einträge)
subjectstringneinBetreffzeile. Beim Senden eines Templates weglassen. (max. 998 Zeichen)
textstringneinPlain-Text-Body. Geben Sie text, html oder template an.
htmlstringneinHTML-Body. SendHQ bereinigt ihn und leitet text ab, wenn text fehlt.
reply_tostringneinReply-To-Adresse.
headersobjectneinZusätzliche sichere benutzerdefinierte Header (String-Werte), z. B. {"X-Entity-Ref-ID": "123"}. Routing-Header wie From/To/Message-ID werden von SendHQ gesteuert.
message_classstringneintransactional (Standard) oder marketing. Marketing erfordert einen Marketing-fähigen Tarif oder eine solche Domain und ergänzt die Abmeldeverarbeitung. (eines von transactional, marketing)
reply_to_email_idstringneinAntwort innerhalb einer bestehenden Unterhaltung: die em_…-ID der beantworteten Nachricht. SendHQ setzt In-Reply-To/References und den Thread.
thread_idstringneinExplizite Thread-ID, unter der die Nachricht abgelegt wird.
draft_idstringneinSendet die Anhänge eines gespeicherten Entwurfs mit dieser Nachricht (dr_…). Der Entwurf wird nach erfolgreichem Versand gelöscht.
templateobjectneinSendet ein veröffentlichtes gehostetes Template statt rohem html/text. Erfordert genau einen to-Empfänger und kein cc/bcc; der Betreff stammt aus dem Template. Geben Sie mindestens eines an: id, key.
template.idstringneinTemplate-ID (tmpl_…). Geben Sie id oder key an.
template.keystringneinTemplate-Key wie account-welcome. Geben Sie id oder key an.
template.version_idstringneinOptionale ID des veröffentlichten Releases (tmplv_…). Standard ist das aktuell veröffentlichte Release.
template.dataobjectneinWerte für die typisierten Variablen des Templates.
labelsstring[]neinLabel-Namen oder lbl_…-IDs, unter denen die Nachricht abgelegt wird. Unbekannte Namen werden angelegt. Antworten in der Unterhaltung erben die Labels, und ein Bucket-Label (skip_inbox) hält diese Antworten aus dem Posteingang heraus. Max. 10. (0–10 Einträge)
idempotency_keystringneinIdempotency-Key-Header (max. 200 Zeichen). Verwenden Sie ihn nur, um genau diese Anfrage zu wiederholen. (max. 200 Zeichen)
attachmentsobject[]neinAnzuhängende Dateien (max. 10 Dateien, insgesamt 10 MB). Jede braucht content_base64 (plus filename) oder einen lokalen file_path. (0–10 Einträge) Geben Sie mindestens eines an: content_base64, file_path.
attachments[].filenamestringneinDateiname, den der Empfänger sieht. Bei content_base64 erforderlich; standardmäßig der Basisname von file_path. (max. 255 Zeichen)
attachments[].content_typestringneinMIME-Typ, z. B. application/pdf. Standard ist application/octet-stream.
attachments[].content_base64stringneinStandard-Base64-Dateiinhalt.
attachments[].file_pathstringneinAbsoluter Pfad einer lokalen Datei, die der MCP-Serverprozess lesen kann.
Rückgabe{id: em_…, providerMessageId, threadId, templateId, templateVersionId, isTest}. Angenommen heißt nicht zugestellt: Prüfen Sie anschließend mit list_email_events.
Beispiel für tools/call params
{
  "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"
  }
}
Sendet echte E-Mailssend_batch
POST /emails/batch

Einen Batch individualisierter E-Mails senden

SENDS REAL EMAIL. Sendet 1–100 unabhängige Nachrichten in einer Anfrage (nutzen Sie das für Template-Personalisierung pro Empfänger). Jeder Eintrag hat dieselbe Form wie bei send_email (ohne attachments/idempotency_key). Die Einträge gelingen oder scheitern einzeln: HTTP 207 bedeutet Teilerfolg; prüfen Sie jeweils data[i].ok und data[i].error. Ein idempotency_key deckt den gesamten Batch-Body ab.

ParameterTypErforderlichBeschreibung
emailsobject[]jaZu sendende Nachrichten. (1–100 Einträge) Geben Sie mindestens eines an: html, text, template.
idempotency_keystringneinIdempotency-Key für den gesamten Batch (max. 200 Zeichen). (max. 200 Zeichen)
Rückgabe{data: [{index, ok, id?, error?: {message, status}}], count, successful, failed}.
Beispiel für tools/call params
{
  "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"
  }
}
Nur lesendlist_emails
GET /emails

E-Mails auflisten und durchsuchen

Listet gesendete (direction: out) und empfangene (direction: in) E-Mails mit Filtern, neueste zuerst. Empfangene E-Mails werden klassifiziert: Den Posteingang eines Menschen lesen Sie mit direction: in, archived: false, category: primary; zum Sichten nutzen Sie important: true; Spam ist ausgeblendet, außer bei category: spam oder include_spam: true. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
directionstringneinin für empfangene, out für gesendete E-Mails. (eines von in, out)
statusstringneinStatusfilter, z. B. queued, sent, delivered, bounced, complained, failed.
domainstringneinNur Nachrichten für diese Domain oder eine durch Kommas getrennte Liste von Domains (trifft auf jede zu).
inbox_idstringneinNur Nachrichten, die dieses Postfach empfangen hat (inb_…).
labelstringneinNur Nachrichten mit diesem Label: eine Label-ID lbl_… oder der exakte Name, oder eine durch Kommas getrennte Liste (trifft auf jedes zu). Mit list_labels sehen Sie die Ordner.
archivedbooleanneinfalse = Posteingangsansicht (empfangene, nicht archivierte E-Mails), true = nur archivierte. Weglassen für alle E-Mails.
categorystringneinprimary (Personen), updates (Newsletter, Massenmails, automatisierte E-Mails) oder spam; oder eine durch Kommas getrennte Liste. Spam ist ausgeblendet, sofern nicht angefordert.
importantbooleanneintrue = nur als wichtig markierte Nachrichten (Antworten auf von Ihnen begonnene Unterhaltungen und als wichtig markierte Absender).
include_spambooleanneinSpam in die Ergebnisse einbeziehen (für Suchen über alle Ordner).
fromstringneinDie Absenderadresse enthält diesen Wert.
tostringneinDie Empfängeradresse enthält diesen Wert.
unreadbooleanneintrue = nur ungelesene, false = nur gelesene.
afterstringneinISO-8601-Zeitstempel; nur Nachrichten, die danach erstellt wurden. (date-time)
beforestringneinISO-8601-Zeitstempel; nur Nachrichten, die davor erstellt wurden. (date-time)
querystringneinFreitextsuche über Betreffs, Texte, Absender-/Empfängeradressen und Anhangsdateinamen. (max. 200 Zeichen)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [E-Mail-Zusammenfassungen], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}
Nur lesendget_email
GET /emails/:email_id

Eine E-Mail abrufen

Ruft eine Nachricht mit Headern, HTML-/Text-Body, Status, Thread-Metadaten und Anhangsmetadaten ab (die Bytes laden Sie mit download_attachment).

ParameterTypErforderlichBeschreibung
email_idstringjaE-Mail-ID (beginnt mit em_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
RückgabeE-Mail-Objekt: {id, direction, status, from, to, cc, bcc, subject, html, text, threadId, messageId, providerMessageId, readAt, createdAt, attachments: [{id, filename, contentType, sizeBytes, available}]}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}
Ändert Zustandmark_email
PATCH /emails/:email_id

Als gelesen, archiviert, Spam oder wichtig markieren

Aktualisiert eine Nachricht: read, archived, category (primary, updates, spam; nur empfangene E-Mails) und important. Wer Spam meldet oder als wichtig markiert, bringt SendHQ etwas über diesen Absender für künftige E-Mails bei; übergeben Sie learn: false, um nur diese Nachricht zu ändern. Übergeben Sie mindestens ein Feld.

ParameterTypErforderlichBeschreibung
email_idstringjaE-Mail-ID (beginnt mit em_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
readbooleanneintrue = gelesen, false = ungelesen.
archivedbooleanneintrue = archivieren (Posteingang überspringen), false = zurück in den Posteingang verschieben.
categorystringneinVerschiebt eine empfangene Nachricht nach primary, updates oder spam. (eines von primary, updates, spam)
importantbooleanneinMarkiert die Nachricht als wichtig oder hebt die Markierung auf.
learnbooleanneinfalse = dieses Urteil nicht für den Absender merken (Standard true).
RückgabeDas aktualisierte E-Mail-Objekt.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}
Destruktivdelete_email
DELETE /emails/:email_id

Eine E-Mail löschen

DESTRUCTIVE: Löscht eine gespeicherte Nachricht und ihre gespeicherten Anhänge dauerhaft aus SendHQ. Eine bereits zugestellte Nachricht wird dadurch nicht zurückgerufen.

ParameterTypErforderlichBeschreibung
email_idstringjaE-Mail-ID (beginnt mit em_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}
Nur lesendlist_email_events
GET /emails/:email_id/events

Zustell-Events einer E-Mail auflisten

Provider-Events zu einer gesendeten Nachricht: delivery, bounce, complaint, reject, open, click. Das ist der Beleg dafür, ob eine Nachricht zugestellt wurde oder warum sie fehlschlug. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
email_idstringjaE-Mail-ID (beginnt mit em_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [{event_type, recipient, reason, created_at, …}], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}
Nur lesendget_thread
GET /threads/:thread_id

Eine Unterhaltung abrufen

Ruft alle Nachrichten einer Unterhaltung in chronologischer Reihenfolge ab (gesendet und empfangen), jeweils mit Anhangsmetadaten.

ParameterTypErforderlichBeschreibung
thread_idstringjaThread-ID (meist die em_…-ID der ersten Nachricht; siehe threadId bei jeder E-Mail). (max. 128 Zeichen)
Rückgabe{id, subject, data: [emails]}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
email_idstringja
limitintegernein
offsetintegernein
Returns{emailId, status, timeline, count, limit, offset}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
thread_idstringja
Returns{threadId, delivered, bounced, complained, failed, messages}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "thread_delivery",
  "arguments": {
    "thread_id": "thr_123"
  }
}

Labels und automatische Ablageregeln

Nur lesendlist_labels
GET /labels

Labels auflisten

Listet die Labels (Ordner) des Workspace mit Gesamtzahl, Zahl ungelesener Nachrichten und ihren automatischen Ablageregeln auf. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [{id, name, color, totalCount, unreadCount, rules: [...]}], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_labels",
  "arguments": {}
}
Nur lesendget_label
GET /labels/:label_id

Ein Label abrufen

Ruft ein Label mit Zählern und automatischen Ablageregeln ab.

ParameterTypErforderlichBeschreibung
label_idstringjaLabel-ID (beginnt mit lbl_) oder der exakte Label-Name. (max. 128 Zeichen)
RückgabeLabel-Objekt.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}
Ändert Zustandcreate_label
POST /labels

Ein Label erstellen

Erstellt ein ordnerartiges Label. Setzen Sie skip_inbox: true, um daraus einen Bucket zu machen, den ein Agent besitzt: Senden Sie mit labels: [name], und die Antworten werden im Label abgelegt und aus dem Posteingang herausgehalten. Optionale automatische Ablageregeln legen neue gesendete/empfangene E-Mails ab (jede Bedingung einer Regel muss zutreffen). Setzen Sie apply_to_existing, um auch gespeicherte E-Mails abzulegen.

ParameterTypErforderlichBeschreibung
namestringjaLabel-Name, z. B. Billing oder Clients/Acme. Pro Workspace eindeutig (Groß-/Kleinschreibung wird nicht unterschieden). (max. 64 Zeichen)
colorstringneinHex-Farbe wie #1a73e8. Optional.
skip_inboxbooleanneinBucket-Modus: Empfangene E-Mails, die dieses Label erhalten (per Regel, per Antwort auf eine mit diesem Label gesendete Unterhaltung oder von Hand), werden archiviert und erscheinen nur im Label, nicht im Posteingang.
rulesobject[]neinOptionale automatische Ablageregeln (max. 20). Jede braucht mindestens eines von inbox_id, from, to, subject. (0–20 Einträge)
rules[].directionstringneinNur in (empfangene) oder out (gesendete) E-Mails. Weglassen für beide. (eines von in, out)
rules[].inbox_idstringneinNur E-Mails, die dieses Postfach empfangen hat (inb_…). Legt jede Empfangsadresse in einem eigenen Ordner ab.
rules[].fromstringneinAbsender enthält diesen Text (Groß-/Kleinschreibung egal), z. B. @stripe.com. (max. 200 Zeichen)
rules[].tostringneinTo/Cc enthält diesen Text (Groß-/Kleinschreibung egal). (max. 200 Zeichen)
rules[].subjectstringneinBetreff enthält diesen Text (Groß-/Kleinschreibung egal). (max. 200 Zeichen)
rules[].skip_inboxbooleanneinArchiviert passende empfangene E-Mails, sodass sie nur im Label-Ordner erscheinen, nicht im Posteingang.
apply_to_existingbooleanneinLegt auch bereits gespeicherte E-Mails ab, die zu den Regeln passen.
RückgabeDas erstellte Label mit Regeln.
Beispiel für tools/call params
{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}
Ändert Zustandupdate_label
PATCH /labels/:label_id

Ein Label umbenennen, umfärben oder zum Bucket machen

Benennt ein Label um, ändert seine Farbe oder schaltet den Bucket-Modus (skip_inbox) um. Beim Einschalten des Bucket-Modus werden empfangene E-Mails archiviert, die bereits im Label liegen.

ParameterTypErforderlichBeschreibung
label_idstringjaLabel-ID (beginnt mit lbl_) oder der exakte Label-Name. (max. 128 Zeichen)
namestringneinNeuer Name. (max. 64 Zeichen)
colorstringneinNeue Hex-Farbe.
skip_inboxbooleanneinBucket-Modus: Empfangene E-Mails, die dieses Label erhalten (per Regel, per Antwort auf eine mit diesem Label gesendete Unterhaltung oder von Hand), werden archiviert und erscheinen nur im Label, nicht im Posteingang.
RückgabeAktualisiertes Label.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}
Destruktivdelete_label
DELETE /labels/:label_id

Ein Label löschen

DESTRUCTIVE: Löscht ein Label und seine Regeln. Die E-Mail selbst bleibt erhalten; sie verliert nur dieses Label.

ParameterTypErforderlichBeschreibung
label_idstringjaLabel-ID (beginnt mit lbl_) oder der exakte Label-Name. (max. 128 Zeichen)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}
Ändert Zustandcreate_label_rule
POST /labels/:label_id/rules

Eine automatische Ablageregel hinzufügen

Fügt einem Label eine Regel hinzu, damit passende neue E-Mails automatisch abgelegt werden. Jede von Ihnen gesetzte Bedingung muss zutreffen. Mit inbox_id erhält eine Empfangsadresse einen eigenen Ordner; mit skip_inbox bleibt sie aus dem Posteingang heraus.

ParameterTypErforderlichBeschreibung
label_idstringjaLabel-ID (beginnt mit lbl_) oder der exakte Label-Name. (max. 128 Zeichen)
directionstringneinNur in (empfangene) oder out (gesendete) E-Mails. Weglassen für beide. (eines von in, out)
inbox_idstringneinNur E-Mails, die dieses Postfach empfangen hat (inb_…). Legt jede Empfangsadresse in einem eigenen Ordner ab.
fromstringneinAbsender enthält diesen Text (Groß-/Kleinschreibung egal), z. B. @stripe.com. (max. 200 Zeichen)
tostringneinTo/Cc enthält diesen Text (Groß-/Kleinschreibung egal). (max. 200 Zeichen)
subjectstringneinBetreff enthält diesen Text (Groß-/Kleinschreibung egal). (max. 200 Zeichen)
skip_inboxbooleanneinArchiviert passende empfangene E-Mails, sodass sie nur im Label-Ordner erscheinen, nicht im Posteingang.
apply_to_existingbooleanneinLegt auch bereits gespeicherte E-Mails ab, die passen.
Rückgabe{id: lrule_…, labelId, direction, inboxId, from, to, subject, skipInbox}.
Beispiel für tools/call params
{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}
Destruktivdelete_label_rule
DELETE /labels/:label_id/rules/:rule_id

Eine automatische Ablageregel löschen

DESTRUCTIVE: Entfernt eine automatische Ablageregel. Bereits abgelegte E-Mails behalten ihr Label.

ParameterTypErforderlichBeschreibung
label_idstringjaLabel-ID (beginnt mit lbl_) oder der exakte Label-Name. (max. 128 Zeichen)
rule_idstringjaRegel-ID (beginnt mit lrule_), aus get_label. (max. 128 Zeichen)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}
Ändert Zustandlabel_email
POST /emails/:email_id/labels

Labels einer E-Mail hinzufügen oder entfernen

Verschiebt eine Nachricht zwischen Ordnern: Labels per Name oder lbl_…-ID hinzufügen und/oder entfernen. Unbekannte Namen in add werden angelegt, es sei denn create ist false.

ParameterTypErforderlichBeschreibung
email_idstringjaE-Mail-ID (beginnt mit em_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
addstring[]neinHinzuzufügende Labels. (0–10 Einträge)
removestring[]neinZu entfernende Labels. (0–10 Einträge)
createbooleanneinLegt unbekannte Labels in add an (Standard true).
RückgabeDie aktualisierte E-Mail mit labels.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

Entwürfe, Anhänge und Absenderidentitäten

Nur lesendlist_sending_identities
GET /sending-identities

Verifizierte Absenderidentitäten auflisten

Adressen und Domains, von denen dieser Workspace jetzt senden kann (verifizierte Domains, ihr Standard-From und aktive Postfachadressen). Rufen Sie das vor send_email auf, um ein gültiges from zu wählen.

Keine Parameter.

Rückgabe{domains: [Namen verifizierter Domains], addresses: [Absenderadressen], localParts: [...]}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_sending_identities",
  "arguments": {}
}
Ändert Zustandcreate_draft
POST /drafts

Einen Entwurf erstellen

Erstellt einen Composer-Entwurf. Entwürfe enthalten Anhänge: Erstellen Sie einen Entwurf, rufen Sie upload_attachment auf und senden Sie dann send_email mit draft_id. Sendet nichts.

ParameterTypErforderlichBeschreibung
fromstringneinAbsenderadresse einer verifizierten Domain (kann beim Entwerfen leer sein).
tostring[]neinEmpfänger. (0–100 Einträge)
ccstring[]neinEmpfänger in Kopie (Cc). (0–100 Einträge)
bccstring[]neinEmpfänger in Blindkopie (Bcc). (0–100 Einträge)
subjectstringneinBetreffzeile. (max. 998 Zeichen)
htmlstringneinHTML-Body.
textstringneinPlain-Text-Body.
reply_to_email_idstringneinE-Mail-ID, auf die dieser Entwurf antwortet.
thread_idstringneinThread-ID, zu der dieser Entwurf gehört.
RückgabeEntwurfsobjekt {id: dr_…, from, to, cc, bcc, subject, html, text, attachments: []}.
Beispiel für tools/call params
{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}
Nur lesendlist_drafts
GET /drafts

Entwürfe auflisten

Listet Composer-Entwürfe auf, zuletzt aktualisierte zuerst. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [Entwürfe], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_drafts",
  "arguments": {}
}
Nur lesendget_draft
GET /drafts/:draft_id

Einen Entwurf abrufen

Ruft einen Entwurf mit seinen Anhangsmetadaten ab.

ParameterTypErforderlichBeschreibung
draft_idstringjaEntwurfs-ID (beginnt mit dr_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
RückgabeEntwurfsobjekt mit attachments.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
Ändert Zustandupdate_draft
PUT /drafts/:draft_id

Entwurfsinhalt ersetzen

Ersetzt Inhalt und Empfänger eines Entwurfs. Das ist ein vollständiger Ersatz: Weggelassene Felder werden geleert, lesen Sie daher zuerst get_draft und senden Sie jedes Feld mit, das erhalten bleiben soll. Anhänge bleiben unberührt.

ParameterTypErforderlichBeschreibung
draft_idstringjaEntwurfs-ID (beginnt mit dr_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
fromstringneinAbsenderadresse einer verifizierten Domain (kann beim Entwerfen leer sein).
tostring[]neinEmpfänger. (0–100 Einträge)
ccstring[]neinEmpfänger in Kopie (Cc). (0–100 Einträge)
bccstring[]neinEmpfänger in Blindkopie (Bcc). (0–100 Einträge)
subjectstringneinBetreffzeile. (max. 998 Zeichen)
htmlstringneinHTML-Body.
textstringneinPlain-Text-Body.
reply_to_email_idstringneinE-Mail-ID, auf die dieser Entwurf antwortet.
thread_idstringneinThread-ID, zu der dieser Entwurf gehört.
RückgabeAktualisiertes Entwurfsobjekt.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}
Destruktivdelete_draft
DELETE /drafts/:draft_id

Einen Entwurf verwerfen

DESTRUCTIVE: Verwirft einen Entwurf und löscht seine gespeicherten Anhänge dauerhaft.

ParameterTypErforderlichBeschreibung
draft_idstringjaEntwurfs-ID (beginnt mit dr_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}
Ändert Zustandupload_attachment
POST /drafts/:draft_id/attachments

Einen Anhang zu einem Entwurf hochladen

Lädt eine Datei zu einem Entwurf hoch (max. 10 Dateien und insgesamt 10 MB pro Nachricht). Geben Sie content_base64 oder einen lokalen file_path an. Anhänge erfordern beim Senden einen bezahlten Tarif.

Geben Sie mindestens eines an: content_base64, file_path.

ParameterTypErforderlichBeschreibung
draft_idstringjaEntwurfs-ID (beginnt mit dr_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
filenamestringneinDateiname, den der Empfänger sieht. Standard ist der Basisname von file_path. (max. 255 Zeichen)
content_typestringneinMIME-Typ, z. B. application/pdf. Standard ist application/octet-stream.
content_base64stringneinStandard-Base64-Dateiinhalt.
file_pathstringneinAbsoluter Pfad einer lokalen Datei, die der MCP-Serverprozess lesen kann.
Rückgabe{id: att_…, filename, contentType, sizeBytes, available}.
Beispiel für tools/call params
{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}
Nur lesenddownload_attachment
GET /attachments/:attachment_id

Einen Anhang herunterladen

Lädt einen privaten Anhang herunter (gesendet, empfangen oder aus einem Entwurf). Gibt Base64-Inhalt zurück oder schreibt die Datei, wenn save_to_path gesetzt ist (überschreibt nicht, außer overwrite ist true).

ParameterTypErforderlichBeschreibung
attachment_idstringjaAnhangs-ID (beginnt mit att_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
save_to_pathstringneinOptionaler absoluter lokaler Pfad, in den die Datei geschrieben wird, statt Base64 zurückzugeben.
overwritebooleanneinErlaubt das Ersetzen einer vorhandenen Datei unter save_to_path. Standard false.
Rückgabe{attachment_id, filename, content_type, size_bytes, content_base64} oder {attachment_id, filename, content_type, size_bytes, saved_to}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}
Destruktivdelete_attachment
DELETE /attachments/:attachment_id

Einen Anhang löschen

DESTRUCTIVE: Löscht einen gespeicherten Anhang dauerhaft (zum Beispiel, um vor dem Senden eine Datei aus einem Entwurf zu entfernen).

ParameterTypErforderlichBeschreibung
attachment_idstringjaAnhangs-ID (beginnt mit att_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

Gehostete Templates

Nur lesendlist_templates
GET /templates

Gehostete Templates auflisten

Listet gehostete E-Mail-Templates mit Veröffentlichungsstatus und Nutzung auf. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
lifecyclestringneinactive (Standard), archived oder all. (eines von active, archived, all)
querystringneinSuche nach Name oder Key. (max. 120 Zeichen)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [Templates], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}
Ändert Zustandcreate_template
POST /templates

Ein gehostetes Template erstellen

Erstellt ein Template mit bearbeitbarem Entwurf, optional aus einer Vorlage (welcome, reset, receipt oder blank). Veröffentlichen Sie es, bevor Sie per Key senden.

ParameterTypErforderlichBeschreibung
namestringjaName für Menschen. (max. 120 Zeichen)
keystringneinStabiler Sende-Key: Kleinbuchstaben, Ziffern, Bindestriche; beginnt mit einem Buchstaben (2–64 Zeichen). Wird aus dem Namen abgeleitet, wenn er fehlt.
starterstringneinStartinhalt. (eines von blank, welcome, reset, receipt)
Rückgabe{template, draft, activeVersion, versions, usage}.
Beispiel für tools/call params
{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}
Nur lesendget_template
GET /templates/:template_id

Ein Template abrufen

Ruft den aktuellen Entwurf eines Templates (mit revision), das aktive veröffentlichte Release, den Release-Verlauf und die Nutzung ab. Akzeptiert ID oder Key.

ParameterTypErforderlichBeschreibung
template_idstringjaTemplate-ID (tmpl_…) oder Key. (max. 128 Zeichen)
Rückgabe{template, draft: {id, revision, subjectTemplate, htmlTemplate, textTemplate, variables, sampleData, …} | null, activeVersion, versions, usage}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Ändert Zustandupdate_template_draft
PUT /templates/:template_id/draft

Einen Template-Entwurf speichern

Speichert den bearbeitbaren Entwurf des Templates mit optimistischer Nebenläufigkeitskontrolle: Übergeben Sie die aktuelle revision aus get_template (409 bedeutet, dass jemand anderes zuerst gespeichert hat; erneut lesen und wiederholen). Das ist ein vollständiger Ersatz des Entwurfsinhalts: Weggelassene Felder werden geleert, senden Sie daher jedes Feld mit, das erhalten bleiben soll. Verwenden Sie {{variable}}-Platzhalter.

ParameterTypErforderlichBeschreibung
template_idstringjaTemplate-ID oder Key. (max. 128 Zeichen)
revisionintegerjaAktuelle Entwurfsrevision aus get_template. (1–…)
namestringneinTemplate-Name. (max. 120 Zeichen)
subject_templatestringneinBetreff mit Platzhaltern. (max. 998 Zeichen)
preheader_templatestringneinVorschautext. (max. 240 Zeichen)
html_templatestringneinHTML-Body mit Platzhaltern.
text_templatestringneinPlain-Text-Body mit Platzhaltern.
fromstringneinStandardabsender für Versände dieses Templates.
reply_tostringneinStandard-Reply-To.
variablesobject[]neinTypisierter Variablenvertrag. Jeder Eintrag: {key (Kleinbuchstaben/Unterstriche), label, type: text|number|url|boolean, required (Standard true), fallback, description}.
variables[].keystringja
variables[].labelstringnein
variables[].typestringnein(eines von text, number, url, boolean)
variables[].requiredbooleannein
variables[].fallbackanynein
variables[].descriptionstringnein
sample_dataobjectneinBeispielwerte für Vorschauen und Tests.
Rückgabe{template, draft: {revision: next}, validation: {valid, findings}}.
Beispiel für tools/call params
{
  "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"
    }
  }
}
Ändert Zustandcreate_template_draft
POST /templates/:template_id/draft

Einen neuen Entwurf aus dem veröffentlichten Release beginnen

Erstellt einen neuen bearbeitbaren Entwurf als Kopie des aktuellen veröffentlichten Releases (409, wenn bereits ein Entwurf existiert oder nichts veröffentlicht ist).

ParameterTypErforderlichBeschreibung
template_idstringjaTemplate-ID oder Key. (max. 128 Zeichen)
Rückgabe{draft}.
Beispiel für tools/call params
{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Nur lesendrender_template
POST /templates/:template_id/render

Eine Template-Vorschau rendern

Rendert die exakte Server-Ausgabe (subject, html, text) für den Entwurf, das veröffentlichte Release oder eine bestimmte Version mit den angegebenen Daten. Sendet nichts. Gibt 422 mit findings zurück, wenn Daten den Variablenvertrag verletzen.

ParameterTypErforderlichBeschreibung
template_idstringjaTemplate-ID oder Key. (max. 128 Zeichen)
version_idstringneinOptionale Versions-ID; Standard ist der Entwurf, dann das veröffentlichte Release.
dataobjectneinVariablenwerte; Standard sind die Beispieldaten der Version.
Rückgabe{subject, html, text, preheader, versionId, versionNumber, isDraft, findings}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}
Sendet echte E-Mailssend_template_test
POST /templates/:template_id/test

Eine Test-E-Mail für ein Template senden

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.

ParameterTypErforderlichBeschreibung
template_idstringjaTemplate-ID oder Key. (max. 128 Zeichen)
tostring[]jaTestempfänger. (1–100 Einträge)
fromstringneinAbsender auf einer verifizierten Domain; Standard ist das From des Templates.
version_idstringneinOptionale Versions-ID.
dataobjectneinVariablenwerte; Standard sind die Beispieldaten.
Rückgabe{id: em_…, providerMessageId, threadId, isTest: true}.
Beispiel für tools/call params
{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}
Ändert Zustandpublish_template
POST /templates/:template_id/publish

Ein Template-Release veröffentlichen

Veröffentlicht den aktuellen Entwurf als unveränderliches Release, das send_email mit template.key verwendet. Schlägt mit 422 findings bei Validierungsfehlern fehl oder mit 409, wenn es den aktiven Variablenvertrag eines bereits produktiv genutzten Templates brechen würde.

ParameterTypErforderlichBeschreibung
template_idstringjaTemplate-ID oder Key. (max. 128 Zeichen)
Rückgabe{template, published}.
Beispiel für tools/call params
{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Ändert Zustandarchive_template
POST /templates/:template_id/archive

Ein Template archivieren

Stoppt neue Versände mit diesem Template (der Verlauf bleibt erhalten; mit restore_template umkehrbar). Jede Integration, die diesen Key sendet, schlägt dann mit 404 fehl.

ParameterTypErforderlichBeschreibung
template_idstringjaTemplate-ID oder Key. (max. 128 Zeichen)
Rückgabe{template}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}
Ändert Zustandrestore_template
POST /templates/:template_id/restore

Ein archiviertes Template wiederherstellen

Macht ein archiviertes Template wieder aktiv.

ParameterTypErforderlichBeschreibung
template_idstringjaTemplate-ID oder Key. (max. 128 Zeichen)
Rückgabe{template}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

Domains und DNS

Nur lesendlist_domains
GET /domains

Domains auflisten

Listet Absenderdomains mit aggregiertem setup_status (verified | checking | pending), DNS-Status pro Eintrag und Inbound-Status auf. Kann langsam sein: Nicht verifizierte Domains werden live neu geprüft. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [Domains mit Einträgen], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_domains",
  "arguments": {}
}
Nur lesendget_domain
GET /domains/:domain_id

Domain-Setup-Details abrufen

Ruft eine Domain mit den exakt zu veröffentlichenden DNS-Einträgen (type, name, value), dem Live-Status jedes Eintrags von zwei öffentlichen Resolvern, dns_issues samt Lösungen und dem Inbound-Status ab.

ParameterTypErforderlichBeschreibung
domain_idstringjaDomain-ID (beginnt mit dom_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{id, name, status, setup_status, dns_propagating, records: [{type, name, value, verified, dns_state}], dns_issues: [{code, message, …}], inbound_domain, inbound_status}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Ändert Zustandadd_domain
POST /domains

Eine Absenderdomain hinzufügen

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.

ParameterTypErforderlichBeschreibung
namestringjaReiner Domainname, z. B. example.com oder mail.example.com. (max. 253 Zeichen)
default_fromstringneinOptionale Standard-Absenderadresse dieser Domain.
Rückgabe{id: dom_…, name, status: pending, records: [...], ses: {configured}}.
Beispiel für tools/call params
{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}
Ändert Zustandverify_domain
POST /domains/:domain_id/verify

Eine Domain verifizieren

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.

ParameterTypErforderlichBeschreibung
domain_idstringjaDomain-ID (beginnt mit dom_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{domain, checks: {ses, dkim, dkim_status}, status: verified|pending}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Destruktivdelete_domain
DELETE /domains/:domain_id

Eine Domain löschen

DESTRUCTIVE: Entfernt die Domain aus dem Workspace, einschließlich ihrer Inbound-Empfangsroute. Versände von ihr schlagen danach sofort fehl. DNS-Einträge bei Ihrem DNS-Provider werden dabei nicht gelöscht.

ParameterTypErforderlichBeschreibung
domain_idstringjaDomain-ID (beginnt mit dom_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Nur lesendget_dns_provider
GET /dns/provider

DNS-Provider und Eintrags-Hosts erkennen

Erkennt den maßgeblichen DNS-Provider der Domain und gibt für jeden Eintrag den relativen Host zurück, der bei diesem Provider einzutragen ist, dazu den empfohlenen DMARC-Eintrag, MX-Hinweise für Inbound und die Angabe, ob die Einrichtung per Klick (Domain Connect) verfügbar ist.

ParameterTypErforderlichBeschreibung
domain_idstringjaDomain-ID (beginnt mit dom_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{detectionStatus, detected, zone, nameservers, recordHosts: {recordId: host}, inbound, recommendations, authentication, providers: {domainConnect: {available, providerName}}}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Eingehende E-Mails

Ändert Zustandsetup_inbound
POST /domains/:domain_id/inbound/setup

Inbound-Empfang für eine Domain aktivieren

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.

ParameterTypErforderlichBeschreibung
domain_idstringjaDomain-ID (beginnt mit dom_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{domain: Empfangsdomain, status: dns_pending|ready, record: {type: MX, name, value}}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Ändert Zustandverify_inbound
POST /domains/:domain_id/inbound/verify

Inbound-MX verifizieren

Prüft den Inbound-MX-Eintrag erneut. Der Status wird ready, wenn beide öffentlichen Resolver ihn sehen.

ParameterTypErforderlichBeschreibung
domain_idstringjaDomain-ID (beginnt mit dom_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{domain, status: ready|dns_pending|propagating|checking, record}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Nur lesendlist_inboxes
GET /inboxes

Inbound-Adressen auflisten

Listet Empfangsadressen auf, optional für eine Domain. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
domain_idstringneinOptionaler Filter nach Domain-ID.
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [{id, address, name, status, domainId}], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}
Nur lesendget_inbox
GET /inboxes/:inbox_id

Ein Postfach abrufen

Ruft eine Inbound-Adresse ab.

ParameterTypErforderlichBeschreibung
inbox_idstringjaPostfach-ID (beginnt mit inb_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
RückgabePostfachobjekt.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}
Ändert Zustandcreate_inbox
POST /inboxes

Eine Inbound-Adresse erstellen

Erstellt eine Adresse wie support@<receiving domain> auf einer Domain, deren Inbound-Status ready ist (führen Sie zuvor setup_inbound und verify_inbound aus). Empfangene E-Mails erscheinen in list_emails mit direction in.

ParameterTypErforderlichBeschreibung
domain_idstringjaDomain-ID (beginnt mit dom_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
local_partstringjaTeil vor dem @, z. B. support. (max. 64 Zeichen)
namestringneinOptionaler Anzeigename.
Rückgabe{id: inb_…, address, name, status: active}.
Beispiel für tools/call params
{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}
Ändert Zustandupdate_inbox
PATCH /inboxes/:inbox_id

Ein Postfach umbenennen, aktivieren oder deaktivieren

Benennt ein Postfach um oder setzt seinen Status auf active / disabled.

ParameterTypErforderlichBeschreibung
inbox_idstringjaPostfach-ID (beginnt mit inb_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
namestringneinNeuer Anzeigename.
statusstringneinNeuer Status. (einer von active, disabled)
RückgabeAktualisiertes Postfach.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}
Sendet echte E-Mailsset_inbox_forwarding
PUT /inboxes/:inbox_id/forwarding

Ein Postfach an eine andere Adresse weiterleiten

SENDS REAL EMAIL, wenn an jemand anderen als den Kontoinhaber weitergeleitet wird: Legt fest, wohin die empfangenen E-Mails eines Postfachs weitergeleitet werden. Die eigene Adresse des Inhabers wird sofort aktiv; jede andere Adresse erhält eine Bestätigungs-E-Mail, und die Weiterleitung bleibt pending, bis dort jemand bestätigt. Übergeben Sie forward_to: null, um die Weiterleitung auszuschalten. Weitergeleitete Kopien kommen von der Postfachadresse, mit dem ursprünglichen Absender als Reply-To.

ParameterTypErforderlichBeschreibung
inbox_idstringjaPostfach-ID (beginnt mit inb_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
forward_tostring,nulljaZieladresse für die Weiterleitung oder null, um die Weiterleitung auszuschalten. (max. 254 Zeichen)
RückgabePostfach mit forwardTo und forwardStatus (off, pending oder active).
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}
Destruktivdelete_inbox
DELETE /inboxes/:inbox_id

Ein Postfach löschen

DESTRUCTIVE: Löscht eine Inbound-Adresse. Bereits empfangene E-Mails bleiben erhalten; neue E-Mails an die Adresse werden ihr nicht mehr zugeordnet.

ParameterTypErforderlichBeschreibung
inbox_idstringjaPostfach-ID (beginnt mit inb_), wie sie ein List- oder Create-Tool zurückgibt. (max. 128 Zeichen)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

Zustellbarkeit, Bounces und Sperrliste

Nur lesenddeliverability_stats
GET /deliverability/stats

Zustellstatistiken der letzten 30 Tage abrufen

Workspace-weite Summen der letzten 30 Tage: sent, delivery, bounce, complaint, reject, open, click und deliveryRate (%).

Keine Parameter.

Rückgabe{window: 30d, sent, delivery, bounce, complaint, reject, open, click, deliveryRate}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
daysintegernein(one of 7, 30, 90)
Returns{days, trend, rolling7d, thresholds, ladder}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
daysintegernein
domainstringnein
limitintegernein
offsetintegernein
Returns{days, data, count, limit, offset}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
daysintegernein
domainstringnein
limitintegernein
offsetintegernein
Returns{days, data, count, limit, offset}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
subjectstringneinThe subject line.
htmlstringneinThe HTML as written, before SendHQ adds its footer or tracking. (max 2000000 chars)
textstringneinThe plain-text part. Compared with the HTML when both are given; scored on its own when there is no HTML. (max 2000000 chars)
fromstringneinThe 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}]}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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>"
  }
}
Nur lesendlist_sender_reputation
GET /deliverability/reputation

Absenderreputation auflisten

Reputationsstatus pro exakter Absenderadresse: active, throttled (niedrigeres Tageslimit) oder paused (Versände liefern 423), mit Grund und Tageslimit. Prüfen Sie das, wenn Versände mit 423 oder 429 fehlschlagen. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [{sender, status, dailyLimit, reason, cleanSince, warnedAt, pausedAt, evaluatedAt}], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_sender_reputation",
  "arguments": {}
}
Nur lesendlist_suppressions
GET /suppressions

Sperrliste auflisten

Sperrliste des Workspace: Empfänger, die nach einem permanenten Bounce oder einer Spam-Beschwerde blockiert wurden. Versände an sie schlagen mit 422 fehl. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [{email, reason, detail, created_at}], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_suppressions",
  "arguments": {}
}
Destruktivremove_suppression
DELETE /suppressions/:email

Eine Bounce-Sperre entfernen

DESTRUCTIVE (schwächt eine Schutzsperre ab): Entfernt eine Bounce-Sperre, damit die Adresse wieder angeschrieben werden kann. Tun Sie das nur, wenn der Mensch bestätigt, dass die Adresse jetzt gültig ist. Sperren wegen Beschwerden können nicht entfernt werden (409).

ParameterTypErforderlichBeschreibung
emailstringjaGesperrte Empfängeradresse. (max. 320 Zeichen)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}
Nur lesendlist_blocked_recipients
GET /blocked-recipients

Blockierte Empfänger auflisten

Jeder Empfänger, den SendHQ ablehnt: Bounces, Beschwerden und domainbezogene Marketing-Abmeldungen, mit einer Zusammenfassung nach Art. Liest bis zu die neuesten 500. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [{email, domain, kind: bounce|complaint|unsubscribe, reason, detail, source, status, created_at}], count, summary: {total, bounce, complaint, unsubscribe}, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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}.

ParameterTypErforderlichBeschreibung
list_idstringneinOnly members of this list (lst_…).
statusstringneinOnly 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)
querystringneinEmail or name contains this text; * is a wildcard on the email. (max 200 chars)
tagstringneinOnly contacts with this tag. (max 60 chars)
sourcestringneinHow the contact was added. (one of form, api, import)
afterstringneinSigned up at or after this time. ISO 8601 date or date-time. (max 40 chars)
beforestringneinSigned up before this time. ISO 8601 date or date-time. (max 40 chars)
segment_idstringneinOnly contacts matching this saved segment (seg_…).
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [contacts with tags, engagement, dormant, country], count, total, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
emailstringjaEmail address. (max 320 chars)
namestringneinDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectneinCustom 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[]neinTags to attach, e.g. ["VIP"]. Up to 50. (0–50 items)
list_idsstring[]neinLists to add the contact to (lst_…). (0–100 items)
statusstringneinsubscribed (default, requires consent_basis) or unsubscribed. (one of subscribed, unsubscribed)
consent_basisstringneinHow 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.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
emailstringjaEmail address. (max 320 chars)
namestringneinDisplay name; the first word is {{first_name}}. (max 200 chars)
fieldsobjectneinCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
tagsstring[]neinTags to add, e.g. ["VIP"]. Existing tags are kept. (0–50 items)
timezonestringneinIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
localestringneinLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
consent_basisstringneinHow 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).
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
contact_idstringjaContact ID (starts with ct_) or the contact's email address. (max 320 chars)
ReturnsThe contact.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
contact_idstringjaContact ID (starts with ct_) or the contact's email address. (max 320 chars)
namestringneinNew display name. (max 200 chars)
fieldsobjectneinCustom 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[]neinReplace all of the contact's tags with these. (0–50 items)
add_tagsstring[]neinTags to add. (0–50 items)
remove_tagsstring[]neinTags to remove. (0–50 items)
statusstringneinOnly unsubscribed is accepted. (one of unsubscribed)
ReturnsThe updated contact.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
contact_idstringjaContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
csvstringjaThe CSV file content, header row first. (max 5242880 chars)
list_idstringneinAdd every accepted row to this list (lst_…).
consent_basisstringjaHow 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[]neinTags to add to every accepted row, e.g. ["imported-2026-11"]. (0–50 items)
update_existingbooleanneinMerge names and fields into contacts that already exist. Their status never changes.
Returns{id, accepted, created, existing, skipped, invalid, errors: [{line, reason}], tags}.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [imports], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
actionstringjaWhat to do. (one of tag, untag, add_to_list, remove_from_list, unsubscribe, delete)
contact_idsstring[]neinContact IDs (ct_…). Use this or filter. (0–10000 items)
filterobjectneinEveryone matching these list_contacts filters. Use this or contact_ids.
filter.list_idstringneinMembers of this list.
filter.statusstringneinOnly 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.querystringneinEmail or name contains; * is an email wildcard. (max 200 chars)
filter.tagstringneinHas this tag. (max 60 chars)
filter.sourcestringneinHow the contact was added. (one of form, api, import)
filter.afterstringneinSigned up at or after. ISO 8601 date or date-time. (max 40 chars)
filter.beforestringneinSigned up before. ISO 8601 date or date-time. (max 40 chars)
filter.segment_idstringneinMatches this segment.
tagsstring[]neinFor tag and untag. (0–50 items)
list_idstringneinFor add_to_list and remove_from_list (lst_…).
confirm_countintegerneinFor 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
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [{tag, count}], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [{key, label, type, createdAt}], count, types, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
field_keystringjaField 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)
labelstringneinLabel shown in the dashboard. Defaults to the key. (max 80 chars)
typestringneintext (default), number, or date. (one of text, number, date)
Returns{key, label, type, createdAt}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
field_keystringjaField 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)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [{id, name, match, conditions, count}], count, fields, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_segments",
  "arguments": {}
}
Read-onlyget_segment
GET /segments/:segment_id

Get a segment

Campaigns: One segment with its conditions and live count.

ParameterTypErforderlichBeschreibung
segment_idstringjaSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Returns{id, name, match, conditions, count}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
matchstringneinall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]neinUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringjatag, 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[].keystringneinCustom field key when field is field. (max 40 chars)
conditions[].opstringjatag: 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,numberneinRequired 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]}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
namestringjaSegment name. (max 120 chars)
matchstringneinall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]neinUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringjatag, 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[].keystringneinCustom field key when field is field. (max 40 chars)
conditions[].opstringjatag: 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,numberneinRequired 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.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
segment_idstringjaSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
namestringneinSegment name. (max 120 chars)
matchstringneinall (default): every condition must match. any: at least one. (one of all, any)
conditionsobject[]neinUp to 20 conditions. Opened and clicked use bot-filtered, estimated engagement. (0–20 items)
conditions[].fieldstringjatag, 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[].keystringneinCustom field key when field is field. (max 40 chars)
conditions[].opstringjatag: 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,numberneinRequired 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.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
segment_idstringjaSegment ID (starts with seg_), as returned by list_segments or create_segment. (max 128 chars)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [lists], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
namestringjaList name, shown on the signup form. (max 200 chars)
descriptionstringneinShort description shown on the signup form. (max 500 chars)
form_enabledbooleanneinPublish the hosted signup form.
form_fromstringneinSender of signup confirmation emails, e.g. Acme <news@example.com>, on a verified domain. (max 320 chars)
redirect_urlstringneinhttps page to open after a signup is confirmed. (max 500 chars)
welcomeobjectneinWelcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledbooleanneinSend it.
welcome.subjectstringneinSubject; merge tags allowed. (max 300 chars)
welcome.htmlstringneinHTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstringneinMarkdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobjectneinPublic 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.enabledbooleanneinPublish the site.
site.slugstring,nullneinAddress after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,nullneinSite title. Defaults to the list name. (max 120 chars)
site.descriptionstring,nullneinShort description under the title. (max 300 chars)
site.accentstring,nullneinAccent color, e.g. #0a7d4f.
ReturnsThe list.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
list_idstringjaList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
ReturnsThe list.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
list_idstringjaList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
namestringneinNew name. (max 200 chars)
descriptionstringneinNew description. (max 500 chars)
form_enabledbooleanneinPublish or unpublish the hosted signup form.
form_fromstringneinSender of signup confirmation emails, on a verified domain. (max 320 chars)
redirect_urlstringneinhttps page to open after a signup is confirmed. (max 500 chars)
welcomeobjectneinWelcome email sent once, from form_from, when someone confirms a signup. Needs subject and html or markdown when enabled.
welcome.enabledbooleanneinSend it.
welcome.subjectstringneinSubject; merge tags allowed. (max 300 chars)
welcome.htmlstringneinHTML body; merge tags allowed. (max 500000 chars)
welcome.markdownstringneinMarkdown body instead of html, rendered with the workspace design. (max 200000 chars)
siteobjectneinPublic 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.enabledbooleanneinPublish the site.
site.slugstring,nullneinAddress after /n/ (3-48 characters, a-z, 0-9, -). Defaults to the list name. (max 48 chars)
site.titlestring,nullneinSite title. Defaults to the list name. (max 120 chars)
site.descriptionstring,nullneinShort description under the title. (max 300 chars)
site.accentstring,nullneinAccent color, e.g. #0a7d4f.
ReturnsThe updated list.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
list_idstringjaList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
list_idstringjaList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idsstring[]neinContact IDs (ct_…). (0–500 items)
emailsstring[]neinContact email addresses. (0–500 items)
Returns{listId, added, notFound, list}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
list_idstringjaList ID (starts with lst_), as returned by a list or create tool. (max 128 chars)
contact_idstringjaContact ID (starts with ct_) or the contact's email address. (max 320 chars)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
statusstringneinOnly broadcasts with this status. (one of draft, sending, sent, cancelled, failed)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [broadcasts], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
namestringneinInternal name. Defaults to the subject. (max 200 chars)
list_idstringneinThe list to send to (lst_…).
fromstringneinSender on a verified domain, e.g. Acme <news@example.com>. (max 320 chars)
reply_tostringneinReply-To address. (max 320 chars)
subjectstringneinSubject line; merge tags allowed. (max 998 chars)
preview_textstringneinInbox preview text shown after the subject. (max 300 chars)
htmlstringneinHTML body; merge tags allowed and escaped.
textstringneinPlain-text body; merge tags allowed.
templateobjectneinA published hosted template instead of subject/html/text. Template variables are filled from the contact's name, email, and fields.
template.idstringnein
template.keystringnein
template.version_idstringnein
markdownstringneinMarkdown 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,nullneinBlock 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.
editorstringneinWhich editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobjectneinWho gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,nullneinOnly list members matching this segment (seg_…), or null for the whole list.
audience.orderstringneinWith a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,nullneinSend to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobjectneinOpen and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensbooleanneinAdd an open pixel.
tracking.clicksbooleanneinRewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobjectneinPublish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledbooleanneinPublish it.
web.slugstring,nullneinIssue address; defaults to the subject. (max 100 chars)
web.pinnedbooleanneinKeep it at the top of the site.
ReturnsThe draft broadcast.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe broadcast.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
namestringneinInternal name. (max 200 chars)
list_idstringneinThe list to send to.
fromstringneinSender on a verified domain. (max 320 chars)
reply_tostringneinReply-To address. (max 320 chars)
subjectstringneinBetreffzeile. (max. 998 Zeichen)
preview_textstringneinInbox preview text. (max 300 chars)
htmlstringneinHTML-Body.
textstringneinPlain-Text-Body.
templateobject,nullneinA published hosted template, or null to remove it.
markdownstringneinMarkdown 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,nullneinBlock 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.
editorstringneinWhich editor the dashboard opens: html or blocks. Set automatically for markdown and content. (one of html, blocks)
audienceobjectneinWho gets it, within the list. Subscribed, non-dormant members only.
audience.segment_idstring,nullneinOnly list members matching this segment (seg_…), or null for the whole list.
audience.orderstringneinWith a limit: signup (default) or engaged (most engaged first). (one of signup, engaged)
audience.limitinteger,nullneinSend to at most this many people (send_broadcast_to_more sends to more later), or null for everyone. (1–10000000)
trackingobjectneinOpen and click tracking, both on by default. Opens are estimates (bot-filtered pixel loads), never proof that someone read the email.
tracking.opensbooleanneinAdd an open pixel.
tracking.clicksbooleanneinRewrite links to signed SendHQ redirects (the unsubscribe link never is).
webobjectneinPublish this issue on the list's newsletter site (see create_list site) once it is sent.
web.enabledbooleanneinPublish it.
web.slugstring,nullneinIssue address; defaults to the subject. (max 100 chars)
web.pinnedbooleanneinKeep it at the top of the site.
ReturnsThe updated draft.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
idempotency_keystringneinIdempotency-Key-Header (max. 200 Zeichen). Verwenden Sie ihn nur, um genau diese Anfrage zu wiederholen. (max. 200 Zeichen)
ReturnsThe broadcast with status sending and totals.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe cancelled broadcast with totals.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
statusstringneinOnly recipients with this outcome. (one of queued, sending, sent, held, skipped, failed)
activitystringneinOnly recipients who did this. (one of opened, clicked, not_opened, not_delivered, bounced, complained, unsubscribed)
querystringneinRecipient email contains this text. (max 200 chars)
includestringneinlinks adds the links each recipient clicked (implied by activity: clicked). (one of links)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [{contactId, email, status, skipReason, emailId, error, provider, deliveredAt, openedAt, clickedAt, opens, clicks, bouncedAt, complainedAt, unsubscribedAt, links?}], count, totals, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast 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}}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
tostring[]neinTest recipients (up to 5). (1–5 items)
contact_idstringneinFill merge tags from this contact (ct_…). (max 320 chars)
rememberbooleanneinSave to as the default test recipients.
Returns{data: [{to, id, status: sent|failed, error?}]}.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
scheduled_atstringjaWhen 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.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe draft broadcast.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
ReturnsThe new draft broadcast.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast ID (starts with bc_), as returned by a list or create tool. (max 128 chars)
limitintegerjaHow many more people at most. (1–10000000)
idempotency_keystringneinIdempotency-Key-Header (max. 200 Zeichen). Verwenden Sie ihn nur, um genau diese Anfrage zu wiederholen. (max. 200 Zeichen)
Returns{added, broadcast}.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
broadcast_idstringjaBroadcast 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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

Keine Parameter.

Returns{postalAddress, design: {accentColor, font, align}, cleanup: {enabled, afterSends, quietDays, subject, body, from}, testRecipients}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
postal_addressstringneinSender's postal address for the footer. Empty string removes it. (max 300 chars)
designobjectneinRendering design for Markdown and block content.
design.accentColorstring,nullneinHex color like #0a7d4f, or null for the default.
design.fontstringneinFont family. (one of sans, serif, mono)
design.alignstringneinText alignment. (one of left, center)
cleanupobjectneinList cleanup of readers who stopped opening.
cleanup.enabledbooleanneinTurn list cleanup on or off.
cleanup.afterSendsintegerneinBroadcasts in a row without an open or click (3-50). (3–50)
cleanup.quietDaysintegerneinDays without engagement (30-730). (30–730)
cleanup.subjectstring,nullneinSubject of the cleanup email; merge tags allowed. (max 200 chars)
cleanup.bodystring,nullneinBody text of the cleanup email. (max 2000 chars)
cleanup.fromstring,nullneinSender on a verified domain. Defaults to the last sent broadcast's sender. (max 320 chars)
test_recipientsstring[]neinDefault addresses for send_broadcast_test (up to 5). (0–5 items)
ReturnsThe updated settings.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
daysintegerneinWindow 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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [{id, url, width, height, size, filename, createdAt}], pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
emailstringjaThe contact's email address. (max 320 chars)
eventstringjaWhat they did: a lowercase letter, then a-z, 0-9, and _ (e.g. checkout_started). Names starting email. are reserved. (max 64 chars)
propertiesobjectneinUp 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_atstringneinWhen 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_keystringneinStable ID for this event (max 200 chars). A second call with the same key records nothing and returns the first result. (max 200 chars)
contactobjectneinChanges to the contact, applied with the event.
contact.namestringneinDisplay name. (max 200 chars)
contact.fieldsobjectneinCustom fields to merge (string, number, or boolean values), e.g. {"plan": "pro"}. A null value removes a field.
contact.timezonestringneinIANA time zone, e.g. Europe/Paris. Automation emails respect sending hours in this zone. (max 64 chars)
contact.localestringneinLanguage tag, e.g. fr or pt-br. Picks the language version of each automation email. (max 35 chars)
contact.consent_basisstringneinHow 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]}.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
domainstringneinOnly 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)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation 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}].
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
keystringjaAddress of the automation: 1-63 characters of a-z, 0-9, and - (e.g. checkout-recovery). (max 63 chars)
namestringjaName shown in the dashboard. (max 200 chars)
audience_labelstringneinWho this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstringneinWhat converting means, in a word or two, e.g. paid. (max 80 chars)
entryobjectneinHow 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.typestringjaEntry type. (one of event, bucket, date_field, manual)
entry.eventstringneinEvent name for an event entry, e.g. checkout_started.
entry.segment_idstringneinSegment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstringneinContact field key for a date_field entry. (max 40 chars)
entry.reentrystringneinWhether someone who finished may enter again. (one of never, after_end)
exit_rulesobjectneinWhen 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,nullneinEvent that counts as converting, e.g. payment_completed.
exit_rules.no_goalbooleanneinTrue when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]neinEvents that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysintegerneinDays before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobjectneinPer-automation settings. Omitted keys keep their value.
settings.exempt_from_holdbooleanneinSkip 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,nullneinAt 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,nullneinStored 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_pctnumberneinPercent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysintegerneinAn email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysintegerneinHow long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positionintegerneinPriority. 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_namestringneinSender display name, e.g. Acme. (max 120 chars)
from_addressstringneinSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringneinReply-To address. (max 320 chars)
stepsobject[]neinThe emails, in order. position defaults to the place in this list. (0–50 items)
steps[].positionintegerneinPosition of the email in the automation, 1 to 50. (1–50)
steps[].subjectstringneinSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
steps[].preheaderstringneinInbox preview line. (max 300 chars)
steps[].contentobjectneinBlock 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[].htmlstringneinHTML body. The unsubscribe footer is added automatically.
steps[].textstringneinPlain-Text-Body.
steps[].editorstringneinHow 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_secondsintegerneinWhen 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[]neinMerge 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_windowbooleanneinSend 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}].
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
namestringneinName shown in the dashboard. (max 200 chars)
audience_labelstringneinWho this is for, in plain words, e.g. Started checkout and left. (max 200 chars)
goal_labelstringneinWhat converting means, in a word or two, e.g. paid. (max 80 chars)
entryobjectneinHow 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.typestringjaEntry type. (one of event, bucket, date_field, manual)
entry.eventstringneinEvent name for an event entry, e.g. checkout_started.
entry.segment_idstringneinSegment ID (seg_…) for a bucket entry. (max 128 chars)
entry.fieldstringneinContact field key for a date_field entry. (max 40 chars)
entry.reentrystringneinWhether someone who finished may enter again. (one of never, after_end)
exit_rulesobjectneinWhen 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,nullneinEvent that counts as converting, e.g. payment_completed.
exit_rules.no_goalbooleanneinTrue when this automation deliberately has no goal.
exit_rules.stop_eventsstring[]neinEvents that take a person out, e.g. ["account_closed"]. (0–20 items)
exit_rules.attribution_daysintegerneinDays before the goal within which an email earns the conversion. Default 14. (1–90)
settingsobjectneinPer-automation settings. Omitted keys keep their value.
settings.exempt_from_holdbooleanneinSkip 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,nullneinAt 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,nullneinStored 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_pctnumberneinPercent of people who enter but are sent nothing, to measure what the emails change (0-100). (0–100)
settings.stale_daysintegerneinAn email more than this many days overdue is skipped instead of sent late. Default 4. (1–365)
settings.resume_after_daysintegerneinHow long a waiting enrolment waits after the automation ahead of it ends. Default 3. (0–365)
positionintegerneinPriority. 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_namestringneinSender display name, e.g. Acme. (max 120 chars)
from_addressstringneinSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringneinReply-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}].
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerjaPosition of the email in the automation, 1 to 50. (1–50)
templatestringneinId 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)
subjectstringneinSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringneinInbox preview line. (max 300 chars)
contentobjectneinBlock 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.
htmlstringneinHTML body. The unsubscribe footer is added automatically.
textstringneinPlain-Text-Body.
editorstringneinHow 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_secondsintegerneinWhen 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[]neinMerge 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_windowbooleanneinSend 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}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerjaPosition of the email in the automation, 1 to 50. (1–50)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerjaPosition of the email in the automation, 1 to 50. (1–50)
localestringjaLanguage tag of the version, e.g. fr or pt-br. (max 35 chars)
subjectstringneinSubject line. Merge tags such as {{ first_name | there }} are filled per contact. (max 998 chars)
preheaderstringneinInbox preview line. (max 300 chars)
contentobjectneinBlock 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.
htmlstringneinHTML body. The unsubscribe footer is added automatically.
textstringneinPlain-Text-Body.
Returns{locale, subject, preheader, content, html, text, updated_at}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
statusstringjaon 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}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
positionintegerjaPosition of the email in the automation, 1 to 50. (1–50)
localestringneinSend 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)
sampleobjectneinValues 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_runbooleanneinSend 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}]}.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
localestringneinSend 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)
sampleobjectneinValues 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}.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringjaEmail address of an existing contact. (max 320 chars)
propertiesobjectneinUp 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_atstringneinThe 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}.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
emailstringjaEmail address of the contact. (max 320 chars)
reasonstringneinWhy, 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}.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
fromstringneinFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringneinLast day of the report as a UTC date (YYYY-MM-DD), inclusive.
domainstringneinOnly 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}]}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
fromstringneinFirst day of the report as a UTC date (YYYY-MM-DD), inclusive.
tostringneinLast 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}]}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
didstringneinWhat the people did. Defaults to entered. (one of entered, sent, delivered, opened, clicked, converted, bounced, unsubscribed, waiting)
stepintegerneinOnly this email of the automation, by its position. (1–50)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
automation_keystringjaAutomation key, as returned by list_automations (e.g. checkout-recovery). (max 63 chars)
contact_idstringjaContact 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}}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

Keine Parameter.

Returns{max_emails, period_days, min_gap_hours, window_start, window_end, weekdays, default_timezone, product_name, sender_name, updated_at}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
max_emailsintegerneinMost automation emails one person may get in period_days. Default 2. (1–50)
period_daysintegerneinThe period max_emails applies to, in days. Default 7. (1–90)
min_gap_hoursintegerneinLeast time between two automation emails to one person, in hours. Default 44. (0–720)
window_startintegerneinFirst hour of the day emails may go out, local time (0-23). Default 9. (0–23)
window_endintegerneinHour sending stops, local time (1-24); must be later than window_start. Default 18. (1–24)
weekdaysinteger[]neinDays emails may go out: 0 = Sunday to 6 = Saturday. Default [1, 2, 3, 4, 5]. (1–7 items)
default_timezonestringneinIANA time zone used for contacts that have none, e.g. Europe/London. (max 64 chars)
product_namestringneinYour product's name, for {{ product_name }}. (max 120 chars)
sender_namestringneinWho the emails are from, for {{ sender_name }}. (max 120 chars)
ReturnsThe updated limits.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
template_idstringjaId 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.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
template_idstringjaId 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)
keystringneinAddress 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)
namestringneinName shown in the dashboard. Defaults to the template's own name. (max 200 chars)
from_namestringneinSender display name, e.g. Acme. (max 120 chars)
from_addressstringneinSender address on a verified workspace domain (see list_sending_identities). (max 320 chars)
reply_tostringneinReply-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.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
contactstringneinOnly this contact: a contact ID or an email address. (max 320 chars)
namestringneinOnly this event, e.g. checkout_started. See list_event_names. (max 64 chars)
fromstringneinEvents from this UTC date (YYYY-MM-DD) or ISO 8601 date-time on. (max 40 chars)
tostringneinEvents up to this UTC date (the whole day) or ISO 8601 date-time. (max 40 chars)
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Returns{data: [{event, words, count}], count, days, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
connection_idstringjaConnection 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}].
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
namestringjaWhat to call it, e.g. Stripe. (max 80 chars)
kindstringjastripe, dodo, or generic. (one of generic, stripe, dodo)
consent_basisstringjaHow 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_prefixstringneinPut in front of every event name, e.g. stripe_. (max 32 chars)
enabledbooleanneinDefaults to true. Pass false to create it switched off.
mappingobjectneinFor a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstringneinWhere the contact's email address is. (max 120 chars)
mapping.eventstringneinWhere the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestringneinOne fixed event name, instead of event. (max 64 chars)
mapping.timestringneinWhere the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstringneinWhere a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]neinThe 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.
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
connection_idstringjaConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
namestringneinA new name. (max 80 chars)
enabledbooleanneintrue: record what arrives. false: answer 404 and record nothing.
consent_basisstringneinHow 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_prefixstringneinPut in front of every event name, e.g. stripe_. (max 32 chars)
mappingobjectneinFor a generic connection: dotted paths into the payload it posts, such as customer.email. email is required, and either event or event_name.
mapping.emailstringneinWhere the contact's email address is. (max 120 chars)
mapping.eventstringneinWhere the payload names what happened. Order Placed becomes the event order_placed. (max 120 chars)
mapping.event_namestringneinOne fixed event name, instead of event. (max 64 chars)
mapping.timestringneinWhere the time it happened is (ISO 8601, or Unix seconds or milliseconds). Defaults to the time of arrival. (max 120 chars)
mapping.idstringneinWhere a unique ID of the message is, so a retried delivery is recorded once. (max 120 chars)
mapping.keepstring[]neinThe 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}.
AnnotationenidempotentHint
Beispiel für tools/call params
{
  "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.

ParameterTypErforderlichBeschreibung
connection_idstringjaConnection ID, as returned by list_connections (e.g. acn_…). (max 128 chars)
Rückgabe{ok: true}.
AnnotationendestructiveHint idempotentHint
Beispiel für tools/call params
{
  "name": "delete_connection",
  "arguments": {
    "connection_id": "acn_123"
  }
}

Konto, Nutzung, Analytics und Schlüssel

Nur lesendget_account
GET /account

Konto, Nutzung und Abrechnung abrufen

E-Mail-Adresse des Kontoinhabers, Tarif/Zugriffsstufe, in der aktuellen Periode genutzte Empfängerzustellungen im Vergleich zum Kontingent, genutzte Domains im Vergleich zum Limit, Anhangstransfer, Reputationszusammenfassung, Abostatus, veröffentlichte Tarife und Workspace-Zähler. Nutzen Sie es, um das verbleibende Kontingent zu prüfen oder zu sehen, an wen die Testphase zustellen kann (die Konto-E-Mail-Adresse).

Keine Parameter.

Rückgabe{user: {email, …}, usage: {domainsUsed, domainLimit, recipientDeliveries, emailQuotaMonth, attachmentBytes, attachmentByteLimit, periodKey}, access: {tier, planCode}, reputation, infrastructure, billing: {status, subscriptions, …}, plans, workspace: {mailer, stats}}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "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.

Keine Parameter.

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}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_account_diagnostics",
  "arguments": {}
}
Nur lesendget_analytics
GET /analytics

Versand-Analytics abrufen

Dashboard-Analytics für die letzten 7, 30 oder 90 Tage: Summen für gesendet/empfangen/zugestellt/gebounct/blockiert/geöffnet/geklickt/Beschwerden, ein tageweiser Verlauf, die wichtigsten Absenderdomains und die häufigsten Betreffs.

ParameterTypErforderlichBeschreibung
daysintegerneinZeitfenster in Tagen: 7, 30 (Standard) oder 90. (eines von 7, 30, 90)
Rückgabe{window, days, metrics, timeline: [{day, sent, received}], domains, topContent}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}
Nur lesendlist_api_keys
GET /keys

Metadaten zu API-Schlüsseln auflisten

Listet Namen, nicht geheime Präfixe und Zeitpunkte der letzten Nutzung von API-Schlüsseln auf. Nur lesend: Dieser MCP-Server kann keine Schlüssel erstellen, rotieren oder widerrufen; das erledigt ein Mensch im Dashboard. Paginiert: Das Ergebnis enthält pagination {offset, limit, returned, total?, has_more, next_offset}.

ParameterTypErforderlichBeschreibung
limitintegerneinSeitengröße. Standard 50. (Standard 50; 1–200)
offsetintegerneinAnzahl der zu überspringenden Datensätze. Verwenden Sie pagination.next_offset der vorherigen Seite. (Standard 0; 0–…)
Rückgabe{data: [{id, name, prefix, lastUsedAt, createdAt}], count, pagination}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "list_api_keys",
  "arguments": {}
}
Nur lesendget_service_health
GET /health

Den Dienststatus von SendHQ prüfen

Prüft, ob die SendHQ API erreichbar ist und welcher Mail-Provider aktiv ist. Benötigt keinen gültigen API-Schlüssel.

Keine Parameter.

Rückgabe{ok, service, mailer}.
AnnotationenreadOnlyHint idempotentHint
Beispiel für tools/call params
{
  "name": "get_service_health",
  "arguments": {}
}

Abdeckung der API

Jede Operation der öffentlichen API und das Tool, das sie abdeckt. Alles, was ein Nutzer im Dashboard tun kann und wofür es eine API gibt, ist abgedeckt; die folgenden Ausnahmen sind beabsichtigt.

EndpunktToolHinweise
POST /emailssend_emailEine E-Mail senden
POST /emails/batchsend_batchBis zu 100 individualisierte Nachrichten senden
GET /emailslist_emailsGesendete und empfangene E-Mails auflisten
GET /emails/:idget_emailEine E-Mail mit ihren Anhängen abrufen
PATCH /emails/:idmark_emailGelesen-Status, Archivierung, Spam, Kategorie oder Wichtigkeit aktualisieren
POST /emails/:id/labelslabel_emailLabels einer E-Mail hinzufügen oder entfernen
DELETE /emails/:iddelete_emailEine gespeicherte E-Mail löschen
GET /emails/:id/eventslist_email_eventsZustell-Events einer E-Mail auflisten
GET /threads/:idget_threadEine Unterhaltung chronologisch abrufen
GET /labelslist_labelsLabels mit Nachrichtenzahlen und Ablageregeln auflisten
POST /labelscreate_labelEin Label erstellen, optional mit automatischen Ablageregeln
GET /labels/:idget_labelEin Label per ID oder Name abrufen
PATCH /labels/:idupdate_labelEin Label umbenennen, umfärben oder zum Bucket machen
DELETE /labels/:iddelete_labelEin Label löschen, ohne seine E-Mails zu löschen
POST /labels/:id/rulescreate_label_ruleEinem Label eine automatische Ablageregel hinzufügen
DELETE /labels/:id/rules/:rule_iddelete_label_ruleEine automatische Ablageregel löschen
POST /draftscreate_draftEinen Composer-Entwurf erstellen
GET /draftslist_draftsComposer-Entwürfe auflisten
GET /drafts/:idget_draftEinen Entwurf und Anhänge abrufen
PUT /drafts/:idupdate_draftEntwurfsinhalt ersetzen
DELETE /drafts/:iddelete_draftEinen Entwurf verwerfen
POST /drafts/:id/attachmentsupload_attachmentEinen Anhang zu einem Entwurf hochladen
GET /attachments/:iddownload_attachmentEinen privaten Anhang herunterladen
DELETE /attachments/:iddelete_attachmentEinen privaten Anhang löschen
GET /sending-identitieslist_sending_identitiesVerifizierte Absenderidentitäten auflisten
GET /templateslist_templatesGehostete Templates auflisten
POST /templatescreate_templateEin gehostetes Template erstellen
GET /templates/:idget_templateEntwürfe, Releases und Nutzung abrufen
PUT /templates/:id/draftupdate_template_draftEinen Template-Entwurf automatisch speichern
POST /templates/:id/draftcreate_template_draftEinen neuen Entwurf aus dem veröffentlichten Release erstellen
POST /templates/:id/renderrender_templateDie exakte Server-Ausgabe rendern
POST /templates/:id/testsend_template_testEinen Test-Snapshot senden
POST /templates/:id/publishpublish_templateEin unveränderliches Template-Release veröffentlichen
POST /templates/:id/archivearchive_templateEin Template archivieren
POST /templates/:id/restorerestore_templateEin archiviertes Template wiederherstellen
POST /domainsadd_domainEine Absenderdomain hinzufügen
GET /domainslist_domainsDomains und zwischengespeicherten DNS-Status auflisten
GET /domains/:idget_domainDomain-Setup-Details abrufen
POST /domains/:id/verifyverify_domainRefresh domain and DNS verification
POST /domains/:id/inbound/setupsetup_inboundProvision inbound receiving
POST /domains/:id/inbound/verifyverify_inboundInbound-MX-Routing verifizieren
DELETE /domains/:iddelete_domainEine Domain löschen
GET /dns/providerget_dns_providerDen maßgeblichen DNS-Provider und die relativen Eintrags-Hosts erkennen
GET /dns/domain-connect/connectget_domain_connect_linkEinen Domain-Connect-Zustimmungslink für die DNS-Einrichtung per Klick erstellen
POST /inboxescreate_inboxEine Inbound-Adresse erstellen
GET /inboxeslist_inboxesInbound-Adressen auflisten
GET /inboxes/:idget_inboxEine Inbound-Adresse abrufen
PATCH /inboxes/:idupdate_inboxEin Postfach umbenennen, aktivieren oder deaktivieren
PUT /inboxes/:id/forwardingset_inbox_forwardingDie empfangenen E-Mails eines Postfachs an eine andere Adresse weiterleiten
DELETE /inboxes/:iddelete_inboxEin Postfach löschen und die Nachrichten behalten
GET /deliverability/statsdeliverability_statsZustellstatistiken der letzten 30 Tage abrufen
GET /deliverability/reputationlist_sender_reputationReputationsstatus pro exakter Absenderidentität auflisten
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_suppressionsSperrlisteneinträge des Workspace auflisten
DELETE /suppressions/:emailremove_suppressionEine zulässige Bounce-Sperre entfernen
GET /blocked-recipientslist_blocked_recipientsBounces, Beschwerden und Abmeldungen auflisten
GET /webhooksnicht verfügbarWebhook 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 /webhooksnicht verfügbarWebhook 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/:idnicht verfügbarWebhook 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/:idnicht verfügbarWebhook 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/:idnicht verfügbarWebhook 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-secretnicht verfügbarWebhook 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/testnicht verfügbarWebhook 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/deliveriesnicht verfügbarWebhook 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/:deliveryIdnicht verfügbarWebhook 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/retrynicht verfügbarWebhook 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/exportnicht verfügbarImage 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/imagesnicht verfügbarImage 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/batchnicht verfügbarHistory 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-historynicht verfügbarHistory 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/previewnicht verfügbarThese 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/testnicht verfügbarThese 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/addressnicht verfügbarThe 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_accountKonto, Nutzung, Abrechnungsstatus und Workspace-Zähler mit einem API-Schlüssel abrufen
GET /account/diagnosticsget_account_diagnosticsDiagnose sending and receiving problems in the workspace
GET /analyticsget_analyticsDashboard-Versand-Analytics für 7, 30 oder 90 Tage abrufen
GET /profileget_accountReines Sitzungs-Gegenstück zu GET /account; der MCP-Server liest die Route für API-Schlüssel.
POST /billing/checkoutnicht verfügbarÄnderungen an der Abrechnung sind bewusst nur in einer Sitzung möglich und erfordern den Kontoinhaber im Dashboard. Der Abrechnungsstatus ist mit get_account lesbar.
POST /billing/cancelnicht verfügbarÄnderungen an der Abrechnung sind bewusst nur in einer Sitzung möglich und erfordern den Kontoinhaber im Dashboard. Der Abrechnungsstatus ist mit get_account lesbar.
POST /keysnicht verfügbarBewusst ausgeschlossen: Ein Agent darf keine Zugangsdaten erzeugen oder vernichten. Schlüssel verwaltet ein Mensch im Dashboard.
GET /keyslist_api_keysAPI-Schlüssel-Metadaten auflisten
DELETE /keys/:idnicht verfügbarBewusst ausgeschlossen: Ein Agent darf keine Zugangsdaten erzeugen oder vernichten. Schlüssel verwaltet ein Mensch im Dashboard.

Bewusst nicht verfügbar

FähigkeitEndpunkteGrund
API-Schlüssel erstellen, rotieren, widerrufen oder löschenPOST /keys, DELETE /keys/:idBewusst ausgeschlossen: Ein Agent darf keine Zugangsdaten erzeugen oder vernichten. Schlüssel verwaltet ein Mensch im Dashboard.
Einen Checkout starten oder ein Abonnement kündigenPOST /billing/checkout, POST /billing/cancelÄnderungen an der Abrechnung sind bewusst nur in einer Sitzung möglich und erfordern den Kontoinhaber im Dashboard. Der Abrechnungsstatus ist mit get_account lesbar.
Cloudflare-DNS per Klick (OAuth)GET /api/dns/cloudflare/connectErfordert eine interaktive Browsersitzung und die OAuth-Zustimmung bei Cloudflare. Nutzen Sie stattdessen die Einträge aus get_domain, die Hosts aus get_dns_provider oder get_domain_connect_link.
Registrieren, Anmelden, Abmelden, Verknüpfung mit Google-Konto/api/auth/*Authentifizierung im Browser durch Menschen; der MCP-Server authentifiziert sich mit einem API-Schlüssel.
Kontaktformular für den SupportPOST /api/contactÖffentliches Formular der Marketing-Website für Menschen, keine Workspace-Operation.
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.

Maschinenlesbarer Katalog: /docs/mcp/tools.json (Schemas, Annotationen, Endpunktzuordnung, Ausnahmen). Markdown-Version dieser Seite: /docs/mcp.md. Mit installierter CLI gibt sendhq commands --format json denselben Katalog aus.