API reference

Emails and threads

Send, retrieve, search, reply, and inspect delivery events.

Filter emails and threads

POST/emails

API key

Send one email

Send transactional HTML, text, or hosted-template content from a verified workspace domain. Direct sends may set message_class to marketing when enabled for the verified sender domain. Marketing adds managed unsubscribe headers unless a configured first-party integration supplies its own visible HTTPS one-click URL.

Optional headersIdempotency-Key

Request

curl https://sendhq.cc/api/v1/emails \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"from":"Acme <hello@example.com>","to":["customer@example.net"],"subject":"Welcome aboard","html":"<h1>Welcome</h1><p>Your workspace is ready.</p>","text":"Welcome. Your workspace is ready."}'

201 Response

{
  "id": "em_…",
  "providerMessageId": "provider-id",
  "threadId": "em_…"
}

POST/emails/batch

API key

Send up to 100 individualized messages

Optional headersIdempotency-Key

Request

curl https://sendhq.cc/api/v1/emails/batch \
  -X POST \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":[{"from":"Acme <hello@example.com>","to":["customer@example.net"],"subject":"Welcome aboard","html":"<h1>Welcome</h1><p>Your workspace is ready.</p>","text":"Welcome. Your workspace is ready."}]}'

201 Response

{
  "data": [
    {
      "index": 0,
      "ok": true,
      "id": "em_…"
    }
  ],
  "count": 1,
  "successful": 1,
  "failed": 0
}

GET/emails

API key

List sent and received email

Newest-first list with filters. `query` searches subjects, bodies, participants, and attachment filenames. `label`, `domain`, and `category` accept one value or a comma-separated list (matches any); labels may be IDs or names. `archived=false` returns the Inbox view for received mail. Received mail is classified as `primary`, `updates` (newsletters, bulk, and automated mail), or `spam`, and flagged `important`; spam is excluded unless `category=spam` or `include_spam=true`.

Query parametersdirectionstatusdomaininbox_idlabelarchivedcategoryimportantinclude_spamfromtounreadafterbeforequerylimitoffset

Request

curl https://sendhq.cc/api/v1/emails \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 Response

{
  "data": [],
  "count": 0
}

GET/emails/:id

API key

Retrieve an email and its attachments

Request

curl https://sendhq.cc/api/v1/emails/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 Response

{
  "id": "em_…",
  "direction": "out",
  "status": "sent",
  "attachments": []
}

PATCH/emails/:id

API key

Update read, archive, spam, category, or importance

Set `read`, `archived`, `category` (`primary`, `updates`, or `spam` — received mail only), and `important`. Changing `category` or `important` teaches SendHQ about the sender: reported spam sends that sender's future mail to spam, `Not spam` overrides automatic spam checks for them, and importance sticks to the sender. Pass `learn: false` to change only this message.

Request

curl https://sendhq.cc/api/v1/emails/id_value \
  -X PATCH \
  -H "Authorization: Bearer $SENDHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"spam"}'

200 Response

{
  "id": "em_…",
  "readAt": "2026-08-23T12:00:00.000Z",
  "archivedAt": null,
  "category": "spam",
  "important": false,
  "classification": "you moved it here"
}

DELETE/emails/:id

API key

Delete a retained email

Request

curl https://sendhq.cc/api/v1/emails/id_value \
  -X DELETE \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 Response

{
  "ok": true
}

GET/emails/:id/events

API key

List delivery events for an email

Request

curl https://sendhq.cc/api/v1/emails/id_value/events \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 Response

{
  "data": [],
  "count": 0
}

GET/threads/:id

API key

Retrieve a conversation chronologically

Request

curl https://sendhq.cc/api/v1/threads/id_value \
  -X GET \
  -H "Authorization: Bearer $SENDHQ_API_KEY"

200 Response

{
  "id": "em_…",
  "data": [],
  "count": 0
}