Documentation

sendzy API + MCP

sendzy is a cold email platform: register sending domains, host mailboxes on private servers, and send and read email over REST and MCP. The public APIs are accessible with an API key.

Authentication

Create keys in the console under API Keys, or with POST /api/api-keys. Keys are shown once. Pass a key on every request:

headers

X-Api-Key: sk_yourkey.yoursecret
# or
Authorization: Bearer sk_yourkey.yoursecret

Every key is scoped to one organization. Session-based login (email + password) is for the console; the public APIs use keys only.

REST API

Base URL: https://app.sendzy.dev (dev: http://localhost:3000).

Method	Path	Description
`GET`	`/api/domains`	List all domains with their instances and mailboxes
`POST`	`/api/domains`	Register a domain — body: { name }
`DELETE`	`/api/domains/:id`	Delete a domain
`GET`	`/api/mailboxes`	List all mailboxes
`POST`	`/api/mailboxes`	Create a mailbox — body: { domain_id, user, password?, smtp_host?, smtp_port?, imap_host?, imap_port? }
`PATCH`	`/api/mailboxes/:id`	Update a mailbox — assign instance, rotate password, override hosts
`DELETE`	`/api/mailboxes/:id`	Delete a mailbox
`GET`	`/api/mails`	Inbox — query: ?mailbox_id=&direction=&limit=
`GET`	`/api/mails/threads`	Mails grouped as threads
`POST`	`/api/mails/send-email`	Send an email — body: { mailbox_id \| campaign_id, to, subject, body, thread_id? }
`GET`	`/api/campaigns`	List campaigns
`POST`	`/api/campaigns`	Create a campaign — body: { name, mode?, mailbox_id?, mailbox_ids?, steps: [{ subject, body, delay_hours }], csv?, email_field? }
`GET`	`/api/campaigns/:id`	Campaign detail — steps and contacts
`POST`	`/api/campaigns/:id/contacts`	Upload/replace the contact list (CSV) — body: { csv, email_field }
`PATCH`	`/api/campaigns/:id`	Update ONLY the steps' subject and message — body: { steps: [{ id, subject, body }] }
`POST`	`/api/campaigns/:id/send`	Send all due emails (steps advance per their delays; call repeatedly)
`DELETE`	`/api/campaigns/:id`	Delete a campaign
`GET`	`/api/tools/email-verifier`	Verify an email — query: ?email= — returns { status: "valid" \| "invalid" \| "catch-all" }
`GET`	`/api/api-keys`	List API keys
`POST`	`/api/api-keys`	Create an API key — body: { name }
`DELETE`	`/api/api-keys/:id`	Revoke an API key

Example: send an email

bash

curl -X POST https://app.sendzy.dev/api/mails/send-email \
  -H "X-Api-Key: sk_yourkey.yoursecret" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mbx_123",
    "to": "prospect@target.com",
    "subject": "Quick question",
    "body": "Hey — worth a chat?"
  }'

Instance allocation

By default one instance hosts up to 2 domains / 6 mailboxes (ideal: 1 domain, 3 mailboxes). Pass a custom instance_id when buying a domain, or override smtp_host / imap_host on a mailbox to bring your own infrastructure.

Campaigns

Campaigns control which mailbox sends your emails, as a multi-step sequence with a CSV contact list. Three modes:

Mode	Behavior
`round_robin`	Default. Rotates across every mailbox in your organization — each send goes to the mailbox with the fewest sent mails so volume stays even.
`single`	Always sends from one particular mailbox. Requires `mailbox_id`.
`list`	Round-robins across a chosen list of mailboxes. Requires `mailbox_ids`.

bash

curl -X POST https://app.sendzy.dev/api/campaigns \
  -H "X-Api-Key: sk_yourkey.yoursecret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q4 outbound",
    "mode": "list",
    "mailbox_ids": ["mbx_1", "mbx_2", "mbx_3"],
    "steps": [
      { "subject": "Quick question, {{first_name}}", "body": "Hi {{first_name}} — saw you work at {{company}}." },
      { "subject": "Following up", "body": "Any thoughts, {{first_name}}?", "delay_hours": 72 }
    ],
    "csv": "first_name,company,email\nAda,Acme,ada@acme.io",
    "email_field": "email"
  }'

# Send due emails — first step goes immediately, later steps honor delay_hours.
# Call repeatedly (e.g. every hour) to advance the sequence.
curl -X POST https://app.sendzy.dev/api/campaigns/cmp_123/send \
  -H "X-Api-Key: sk_yourkey.yoursecret"

# Update ONLY the subject and message of existing steps
curl -X PATCH https://app.sendzy.dev/api/campaigns/cmp_123 \
  -H "X-Api-Key: sk_yourkey.yoursecret" \
  -H "Content-Type: application/json" \
  -d '{ "steps": [ { "id": "step_1", "subject": "New subject", "body": "New message" } ] }'

Variables: any CSV column is available as {{ column }} (case-insensitive) in the subject and message, plus {{ email }}. The first step sends immediately; later steps wait delay_hours after the previous step. Updating a campaign allows modifying only the steps' subject and message.

Email verifier

Check whether an email address can receive mail before you send:

bash

curl "https://app.sendzy.dev/api/tools/email-verifier?email=prospect@target.com" \
  -H "X-Api-Key: sk_yourkey.yoursecret"

Response:

json

{ "email": "prospect@target.com", "status": "valid" }

Status	Meaning
`valid`	Syntax is valid, the domain has MX records, and the server rejects unknown recipients.
`invalid`	Bad syntax or the domain has no MX records — it cannot receive mail.
`catch-all`	The mail server accepts any address on the domain, so deliverability of the specific mailbox is unknown.

MCP server

The sendzy MCP server exposes the public APIs as tools for Claude, Cursor and other MCP clients. Same API key auth, one endpoint:

url

https://app.sendzy.dev/mcp

Connect from Claude Code

bash

claude mcp add sendzy \
  --transport http \
  --url https://app.sendzy.dev/mcp \
  --header "X-Api-Key: sk_yourkey.yoursecret"

Connect from Cursor / any MCP client

json

{
  "mcpServers": {
    "sendzy": {
      "url": "https://app.sendzy.dev/mcp",
      "headers": {
        "X-Api-Key": "sk_yourkey.yoursecret"
      }
    }
  }
}

Tools

Tool	Description
`list-domains`	List all domains
`buy-domain`	Register a domain
`delete-domain`	Delete a domain
`list-mailboxes`	List all mailboxes
`create-mailbox`	Create a mailbox on a domain
`update-mailbox`	Assign instance / rotate password / override hosts
`delete-mailbox`	Delete a mailbox
`list-mails`	Sync + list mailbox mails
`list-threads`	Mails grouped as threads
`list-campaigns`	List campaigns with mode and stats
`create-campaign`	Create a campaign with steps and a CSV contact list
`update-campaign`	Update only the steps' subject and message
`upload-contacts`	Upload/replace a campaign's contact list (CSV)
`send-campaign`	Send all due emails for a campaign
`email-verifier`	Verify an email address (valid / invalid / catch-all)
`send-email`	Send an email from a mailbox or via a campaign

Authentication

REST API

Example: send an email

Instance allocation

Campaigns

Email verifier

MCP server

Connect from Claude Code

Connect from Cursor / any MCP client

Tools

Get a key