---
title: Emails and threads API | SendHQ Docs
description: Send, retrieve, search, reply, and inspect delivery events.
canonical: https://sendhq.cc/docs/api-reference/emails
last-updated: 2026-09-07
---
# Emails and threads

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

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 headers** `Idempotency-Key`

```shell
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."}'
```

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

POST `/emails/batch`

API key

## Send up to 100 individualized messages

Send up to 100 individualized messages

**Optional headers** `Idempotency-Key`

```shell
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."}]}'
```

```json
{
  "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 parameters** `direction` `status` `domain` `inbox_id` `label` `archived` `category` `important` `include_spam` `from` `to` `unread` `after` `before` `query` `limit` `offset`

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

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

GET `/emails/:id`

API key

## Retrieve an email and its attachments

Retrieve an email and its attachments

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

```json
{
  "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.

```shell
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"}'
```

```json
{
  "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

Delete a retained email

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

```json
{
  "ok": true
}
```

GET `/emails/:id/events`

API key

## List delivery events for an email

List delivery events for an email

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

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

GET `/threads/:id`

API key

## Retrieve a conversation chronologically

Retrieve a conversation chronologically

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

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