SendHQ MCP server

Send one email

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

Provide at least one of: html, text, template.

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

Send a batch of individualized emails

SENDS REAL EMAIL. Send 1–100 independent messages in one request (use this for per-recipient template personalization). Each item has the same shape as send_email (without attachments/idempotency_key). Items succeed or fail individually: HTTP 207 means partial success; inspect each data[i].ok and data[i].error. One idempotency_key covers the whole batch body.

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

List and search email

List sent (direction: out) and received (direction: in) email newest-first with filters. Received mail is classified: read the human inbox with direction: in, archived: false, category: primary; triage with important: true; spam is hidden unless category: spam or include_spam: true. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_emails",
  "arguments": {
    "direction": "in",
    "unread": true,
    "limit": 25
  }
}

Get one email

Retrieve one message with headers, html/text body, status, thread metadata, and attachment metadata (download bytes with download_attachment).

{
  "name": "get_email",
  "arguments": {
    "email_id": "em_123"
  }
}

Mark read, archived, spam, or important

Update one message: read, archived, category (primary, updates, spam; received mail only), and important. Reporting spam or marking important teaches SendHQ about that sender for future mail; pass learn: false to change only this message. Pass at least one field.

{
  "name": "mark_email",
  "arguments": {
    "email_id": "em_123",
    "read": true
  }
}

Delete an email

DESTRUCTIVE: permanently delete a retained message and its stored attachments from SendHQ. It does not recall a message that was already delivered.

{
  "name": "delete_email",
  "arguments": {
    "email_id": "em_123"
  }
}

List delivery events for an email

Provider events for one sent message: delivery, bounce, complaint, reject, open, click. This is the evidence for whether a message was delivered or why it failed. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_email_events",
  "arguments": {
    "email_id": "em_123"
  }
}

Get a conversation

Retrieve every message in a conversation in chronological order (sent and received), each with attachment metadata.

{
  "name": "get_thread",
  "arguments": {
    "thread_id": "em_123"
  }
}

List labels

List the workspace's labels (folders) with total and unread counts and their auto-filing rules. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_labels",
  "arguments": {}
}

Get a label

Retrieve one label with counts and auto-filing rules.

{
  "name": "get_label",
  "arguments": {
    "label_id": "Billing"
  }
}

Create a label

Create a folder-style label. Set skip_inbox: true to make it a bucket an agent owns: send with labels: [name] and the replies are filed into the label and kept out of the Inbox. Optional auto-filing rules file new sent/received mail (every condition on a rule must match). Set apply_to_existing to also file retained mail.

{
  "name": "create_label",
  "arguments": {
    "name": "Agent/Orders",
    "skip_inbox": true,
    "rules": [
      {
        "from": "@stripe.com"
      }
    ]
  }
}

Rename, recolor, or bucket a label

Rename a label, change its color, or toggle bucket mode (skip_inbox). Turning bucket mode on archives received mail already in the label.

{
  "name": "update_label",
  "arguments": {
    "label_id": "lbl_123",
    "name": "Finance/Billing"
  }
}

Delete a label

DESTRUCTIVE: delete a label and its rules. The email itself is kept; it only loses this label.

{
  "name": "delete_label",
  "arguments": {
    "label_id": "lbl_123"
  }
}

Add an auto-filing rule

Add a rule to a label so matching new mail is filed automatically. Every condition you set must match. Use inbox_id to give a receiving address its own folder; add skip_inbox to keep it out of the Inbox.

{
  "name": "create_label_rule",
  "arguments": {
    "label_id": "Billing",
    "inbox_id": "inb_123",
    "skip_inbox": true
  }
}

Delete an auto-filing rule

DESTRUCTIVE: remove one auto-filing rule. Mail already filed keeps its label.

{
  "name": "delete_label_rule",
  "arguments": {
    "label_id": "lbl_123",
    "rule_id": "lrule_123"
  }
}

Add or remove labels on an email

Move a message between folders: add and/or remove labels by name or lbl_… ID. Unknown names in add are created unless create is false.

{
  "name": "label_email",
  "arguments": {
    "email_id": "em_123",
    "add": [
      "Billing"
    ],
    "remove": [
      "Support"
    ]
  }
}

List verified sender identities

Addresses and domains this workspace can send from right now (verified domains, their default From, and active inbox addresses). Call before send_email to pick a valid from.

No parameters.

{
  "name": "list_sending_identities",
  "arguments": {}
}

Create a draft

Create a composer draft. Drafts hold attachments: create a draft, upload_attachment, then send_email with draft_id. Does not send anything.

{
  "name": "create_draft",
  "arguments": {
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice"
  }
}

List drafts

List composer drafts, most recently updated first. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_drafts",
  "arguments": {}
}

Get a draft

Retrieve one draft with its attachment metadata.

{
  "name": "get_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}

Replace draft content

Replace a draft's content and recipients. This is a full replacement: fields you omit are cleared, so read get_draft first and send every field you want to keep. Attachments are unaffected.

{
  "name": "update_draft",
  "arguments": {
    "draft_id": "dr_123",
    "from": "hello@example.com",
    "to": [
      "owner@example.com"
    ],
    "subject": "Invoice (updated)",
    "text": "Attached."
  }
}

Discard a draft

DESTRUCTIVE: discard a draft and permanently delete its stored attachments.

{
  "name": "delete_draft",
  "arguments": {
    "draft_id": "dr_123"
  }
}

Upload an attachment to a draft

Upload one file to a draft (max 10 files and 10 MB total per message). Provide content_base64 or a local file_path. Attachments require a paid plan at send time.

Provide at least one of: content_base64, file_path.

{
  "name": "upload_attachment",
  "arguments": {
    "draft_id": "dr_123",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_path": "/tmp/invoice.pdf"
  }
}

Download an attachment

Download a private attachment (sent, received, or draft). Returns base64 content, or writes the file when save_to_path is set (refuses to overwrite unless overwrite is true).

{
  "name": "download_attachment",
  "arguments": {
    "attachment_id": "att_123",
    "save_to_path": "/tmp/invoice.pdf"
  }
}

Delete an attachment

DESTRUCTIVE: permanently delete a stored attachment (for example, remove a file from a draft before sending).

{
  "name": "delete_attachment",
  "arguments": {
    "attachment_id": "att_123"
  }
}

List hosted templates

List hosted email templates with publish state and usage. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_templates",
  "arguments": {
    "lifecycle": "active"
  }
}

Create a hosted template

Create a template with an editable draft, optionally from a starter (welcome, reset, receipt, or blank). Publish it before sending by key.

{
  "name": "create_template",
  "arguments": {
    "name": "Account welcome",
    "key": "account-welcome",
    "starter": "welcome"
  }
}

Get a template

Retrieve a template's current draft (with revision), active published release, release history, and usage. Accepts ID or key.

{
  "name": "get_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

Save a template draft

Save the template's editable draft using optimistic concurrency: pass the current revision from get_template (409 means someone else saved first; re-read and retry). This is a full replacement of draft content: omitted fields are cleared, so send every field you want to keep. Use {{variable}} placeholders.

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

Start a new draft from the published release

Create a new editable draft copied from the current published release (409 if a draft already exists or nothing is published).

{
  "name": "create_template_draft",
  "arguments": {
    "template_id": "account-welcome"
  }
}

Render a template preview

Render the exact server output (subject, html, text) for the draft, the published release, or a specific version with the given data. Does not send. Returns 422 with findings when data violates the variable contract.

{
  "name": "render_template",
  "arguments": {
    "template_id": "account-welcome",
    "data": {
      "first_name": "Asha"
    }
  }
}

Send a template test email

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.

{
  "name": "send_template_test",
  "arguments": {
    "template_id": "account-welcome",
    "to": [
      "owner@example.com"
    ]
  }
}

Publish a template release

Publish the current draft as an immutable release that send_email with template.key will use. Fails with 422 findings on validation errors, or 409 if it would break the live variable contract of a template already used in production.

{
  "name": "publish_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

Archive a template

Stop new sends that use this template (history is kept; reversible with restore_template). Any integration sending this key will start failing with 404.

{
  "name": "archive_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

Restore an archived template

Make an archived template active again.

{
  "name": "restore_template",
  "arguments": {
    "template_id": "account-welcome"
  }
}

List domains

List sending domains with aggregate setup_status (verified | checking | pending), per-record DNS state, and inbound status. Can be slow: unverified domains are re-checked live. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_domains",
  "arguments": {}
}

Get domain setup details

Retrieve one domain with the exact DNS records to publish (type, name, value), each record's live state from two public resolvers, dns_issues with fixes, and inbound status.

{
  "name": "get_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Add a sending domain

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.

{
  "name": "add_domain",
  "arguments": {
    "name": "example.com"
  }
}

Verify a domain

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.

{
  "name": "verify_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Delete a domain

DESTRUCTIVE: remove the domain from the workspace, including its inbound receiving route. Sends from it fail immediately afterwards. It does not delete DNS records at your DNS provider.

{
  "name": "delete_domain",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Detect DNS provider and record hosts

Detect the domain's authoritative DNS provider and return the relative host to type into that provider for each record, the recommended DMARC record, inbound MX guidance, and whether one-click setup (Domain Connect) is available.

{
  "name": "get_dns_provider",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Get a one-click DNS setup link

When get_dns_provider reports providers.domainConnect.available, create a signed consent URL. Give it to the human: they open it and approve the DNS change at their provider. Nothing changes until they approve. 409 if unsupported.

{
  "name": "get_domain_connect_link",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Enable inbound receiving for a domain

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.

{
  "name": "setup_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Verify inbound MX

Re-check the inbound MX record. Status becomes ready when both public resolvers see it.

{
  "name": "verify_inbound",
  "arguments": {
    "domain_id": "dom_123"
  }
}

List inbound addresses

List receiving addresses, optionally for one domain. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_inboxes",
  "arguments": {
    "domain_id": "dom_123"
  }
}

Get an inbox

Retrieve one inbound address.

{
  "name": "get_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

Create an inbound address

Create an address such as support@<receiving domain> on a domain whose inbound status is ready (run setup_inbound and verify_inbound first). Received mail appears in list_emails with direction in.

{
  "name": "create_inbox",
  "arguments": {
    "domain_id": "dom_123",
    "local_part": "support",
    "name": "Support"
  }
}

Rename, enable, or disable an inbox

Rename an inbox or set its status to active / disabled.

{
  "name": "update_inbox",
  "arguments": {
    "inbox_id": "inb_123",
    "status": "disabled"
  }
}

Forward an inbox to another address

SENDS REAL EMAIL when forwarding to someone other than the account owner: sets where an inbox's received mail is forwarded. The owner's own address activates immediately; any other address gets a confirmation email and forwarding stays pending until someone there confirms. Pass forward_to: null to turn forwarding off. Forwarded copies come from the inbox address with the original sender as Reply-To.

{
  "name": "set_inbox_forwarding",
  "arguments": {
    "inbox_id": "inb_123",
    "forward_to": "team@example.net"
  }
}

Delete an inbox

DESTRUCTIVE: delete an inbound address. Mail already received is retained; new mail to the address is no longer filed to it.

{
  "name": "delete_inbox",
  "arguments": {
    "inbox_id": "inb_123"
  }
}

Get 30-day delivery stats

Workspace-wide 30-day totals: sent, delivery, bounce, complaint, reject, open, click, and deliveryRate (%).

No parameters.

{
  "name": "deliverability_stats",
  "arguments": {}
}

List sender reputation

Reputation state per exact From address: active, throttled (lower daily limit), or paused (sends return 423), with the reason and daily limit. Check this when sends fail with 423 or 429. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_sender_reputation",
  "arguments": {}
}

List suppressions

Workspace suppression list: recipients blocked after a permanent bounce or a spam complaint. Sends to them fail with 422. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_suppressions",
  "arguments": {}
}

Remove a bounce suppression

DESTRUCTIVE (weakens a safety block): remove a bounce suppression so the address can be mailed again. Only do this when the human confirms the address is now valid. Complaint suppressions cannot be removed (409).

{
  "name": "remove_suppression",
  "arguments": {
    "email": "fixed-mailbox@example.net"
  }
}

List blocked recipients

Every recipient SendHQ will refuse: bounces, complaints, and domain-scoped marketing unsubscribes, with a summary by kind. Reads up to the newest 500. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_blocked_recipients",
  "arguments": {}
}

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

{
  "name": "list_contacts",
  "arguments": {
    "status": "subscribed"
  }
}

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.

{
  "name": "create_contact",
  "arguments": {
    "email": "ada@example.net",
    "name": "Ada Lovelace",
    "consent_basis": "Ticked the newsletter box at checkout on acme.com"
  }
}

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.

{
  "name": "get_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}

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.

{
  "name": "update_contact",
  "arguments": {
    "contact_id": "ct_123",
    "fields": {
      "plan": "team"
    }
  }
}

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.

{
  "name": "delete_contact",
  "arguments": {
    "contact_id": "ct_123"
  }
}

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.

{
  "name": "import_contacts",
  "arguments": {
    "csv": "email,name\nada@example.net,Ada Lovelace\n",
    "consent_basis": "Newsletter signups exported from Mailchimp (double opt-in)"
  }
}

List contact imports

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

{
  "name": "list_contact_imports",
  "arguments": {}
}

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.

{
  "name": "bulk_update_contacts",
  "arguments": {
    "action": "tag",
    "tags": [
      "october"
    ],
    "filter": {
      "list_id": "lst_123",
      "status": "subscribed"
    }
  }
}

List contact tags

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

{
  "name": "list_tags",
  "arguments": {}
}

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.

{
  "name": "list_contact_fields",
  "arguments": {}
}

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.

{
  "name": "set_contact_field",
  "arguments": {
    "field_key": "plan",
    "label": "Plan",
    "type": "text"
  }
}

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.

{
  "name": "delete_contact_field",
  "arguments": {
    "field_key": "plan"
  }
}

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.

{
  "name": "list_segments",
  "arguments": {}
}

Get a segment

Campaigns: One segment with its conditions and live count.

{
  "name": "get_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}

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.

{
  "name": "preview_segment",
  "arguments": {
    "match": "all",
    "conditions": [
      {
        "field": "tag",
        "op": "has",
        "value": "VIP"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}

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.

{
  "name": "create_segment",
  "arguments": {
    "name": "Engaged pro customers",
    "conditions": [
      {
        "field": "fields.plan",
        "op": "equals",
        "value": "pro"
      },
      {
        "field": "opened",
        "op": "in_last_days",
        "value": 90
      }
    ]
  }
}

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.

{
  "name": "update_segment",
  "arguments": {
    "segment_id": "seg_123",
    "name": "Pro customers"
  }
}

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.

{
  "name": "delete_segment",
  "arguments": {
    "segment_id": "seg_123"
  }
}

List contact lists

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

{
  "name": "list_lists",
  "arguments": {}
}

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.

{
  "name": "create_list",
  "arguments": {
    "name": "Product updates"
  }
}

Get a list

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

{
  "name": "get_list",
  "arguments": {
    "list_id": "lst_123"
  }
}

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.

{
  "name": "update_list",
  "arguments": {
    "list_id": "lst_123",
    "form_enabled": false
  }
}

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.

{
  "name": "delete_list",
  "arguments": {
    "list_id": "lst_123"
  }
}

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.

{
  "name": "add_list_contacts",
  "arguments": {
    "list_id": "lst_123",
    "emails": [
      "ada@example.net"
    ]
  }
}

Remove a contact from a list

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

{
  "name": "remove_list_contact",
  "arguments": {
    "list_id": "lst_123",
    "contact_id": "ct_123"
  }
}

List broadcasts

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

{
  "name": "list_broadcasts",
  "arguments": {}
}

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.

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

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.

{
  "name": "get_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}

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.

{
  "name": "update_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "subject": "October product update"
  }
}

Delete a draft broadcast

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

{
  "name": "delete_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}

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.

{
  "name": "send_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "idempotency_key": "october-update"
  }
}

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.

{
  "name": "cancel_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}

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.

{
  "name": "list_broadcast_recipients",
  "arguments": {
    "broadcast_id": "bc_123",
    "status": "failed"
  }
}

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.

{
  "name": "check_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}

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.

{
  "name": "send_broadcast_test",
  "arguments": {
    "broadcast_id": "bc_123",
    "to": [
      "owner@example.com"
    ]
  }
}

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.

{
  "name": "schedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123",
    "scheduled_at": "2026-11-10T09:00:00Z"
  }
}

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.

{
  "name": "unschedule_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}

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.

{
  "name": "duplicate_broadcast",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}

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.

{
  "name": "send_broadcast_to_more",
  "arguments": {
    "broadcast_id": "bc_123",
    "limit": 500,
    "idempotency_key": "october-update-more-1"
  }
}

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.

{
  "name": "get_broadcast_report",
  "arguments": {
    "broadcast_id": "bc_123"
  }
}

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.

No parameters.

{
  "name": "get_newsletter_settings",
  "arguments": {}
}

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.

{
  "name": "update_newsletter_settings",
  "arguments": {
    "postal_address": "Acme Inc., 1 Main St, Springfield",
    "design": {
      "accentColor": "#0a7d4f"
    }
  }
}

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.

{
  "name": "get_campaign_overview",
  "arguments": {
    "days": 30
  }
}

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.

{
  "name": "list_uploaded_images",
  "arguments": {}
}

Get account, usage, and billing

Account owner email, plan/access tier, current-period recipient deliveries used vs quota, domains used vs limit, attachment transfer, reputation summary, subscription state, published plans, and workspace counts. Use it to check remaining quota or who the trial can deliver to (the account email).

No parameters.

{
  "name": "get_account",
  "arguments": {}
}

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.

No parameters.

{
  "name": "get_account_diagnostics",
  "arguments": {}
}

Get sending analytics

Dashboard analytics for the last 7, 30, or 90 days: sent/received/delivered/bounced/blocked/opened/clicked/complaint totals, a daily timeline, top sending domains, and top subjects.

{
  "name": "get_analytics",
  "arguments": {
    "days": 30
  }
}

List API key metadata

List API key names, non-secret prefixes, and last-used times. Read-only: this MCP server cannot create, rotate, or revoke keys; a human does that in the dashboard. Paginated: the result includes pagination {offset, limit, returned, total?, has_more, next_offset}.

{
  "name": "list_api_keys",
  "arguments": {}
}

Check SendHQ service health

Check that the SendHQ API is up and which mail provider is active. Does not need a valid API key.

No parameters.

{
  "name": "get_service_health",
  "arguments": {}
}