> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Email API — Send, Receive, Thread & Reply to Messages

> REST API reference for the Nonhumans Email primitive — send messages, list inbox, retrieve threads, and reply from your agent's mailbox.

Every Nonhumans agent gets a dedicated email address (e.g. `alice@nonhumans.ai`) with a real, deliverable inbox. The Email API lets your agent send outbound messages, read incoming mail, retrieve full message threads, and reply — everything you'd expect from a complete mailbox, accessible over REST.

***

## POST /v1/email/send

Send an email from your agent's address. The `from` address is always your agent's email — you cannot spoof other senders.

```bash theme={null}
curl -X POST https://api.nonhumans.ai/v1/email/send \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["bob@example.com"],
    "subject": "Hello from Alice",
    "text": "Hi Bob, just checking in.",
    "html": "<p>Hi Bob, just checking in.</p>"
  }'
```

<ParamField body="to" type="string[]" required>
  Array of recipient email addresses.
</ParamField>

<ParamField body="cc" type="string[]">
  Array of CC email addresses.
</ParamField>

<ParamField body="bcc" type="string[]">
  Array of BCC email addresses. Recipients are hidden from each other.
</ParamField>

<ParamField body="subject" type="string" required>
  Email subject line. Maximum 998 characters.
</ParamField>

<ParamField body="text" type="string">
  Plain-text body of the email. At least one of `text` or `html` is required.
</ParamField>

<ParamField body="html" type="string">
  HTML body of the email. At least one of `text` or `html` is required.
</ParamField>

<ParamField body="attachments" type="array">
  Array of attachment objects.

  <Expandable title="Attachment fields">
    <ParamField body="filename" type="string" required>
      Name of the attached file as it will appear to the recipient.
    </ParamField>

    <ParamField body="content" type="string" required>
      Base64-encoded file content.
    </ParamField>

    <ParamField body="content_type" type="string" required>
      MIME type of the attachment (e.g. `application/pdf`, `image/png`).
    </ParamField>
  </Expandable>
</ParamField>

**Example response:**

```json theme={null}
{
  "message_id": "msg_01HXYZ789",
  "sent_at": "2024-12-01T14:30:00Z"
}
```

<ResponseField name="message_id" type="string">
  Unique identifier for the sent message. Use this to retrieve or reply to the message later.
</ResponseField>

<ResponseField name="sent_at" type="string (ISO 8601)">
  Timestamp when the message was accepted for delivery.
</ResponseField>

***

## GET /v1/email/messages

List messages in your agent's mailbox. Supports filtering by folder and pagination.

```bash theme={null}
curl "https://api.nonhumans.ai/v1/email/messages?folder=inbox&limit=20" \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

<ParamField query="folder" type="string">
  Mailbox folder to query. One of `inbox`, `sent`, `drafts`. Defaults to `inbox`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of messages to return. Default `20`, max `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response's `next_cursor`.
</ParamField>

<ParamField query="since" type="string (ISO 8601)">
  Only return messages received or sent after this timestamp.
</ParamField>

**Example response:**

```json theme={null}
{
  "messages": [
    {
      "id": "msg_01HXYZ789",
      "from": "bob@example.com",
      "to": ["alice@nonhumans.ai"],
      "subject": "Re: Hello from Alice",
      "snippet": "Hey Alice! All good here...",
      "received_at": "2024-12-01T15:00:00Z",
      "has_attachments": false,
      "read": false
    }
  ],
  "next_cursor": "cur_01HABC..."
}
```

***

## GET /v1/email/messages/{id}

Retrieve the full contents of a single message, including headers, body, and any attachments.

```bash theme={null}
curl https://api.nonhumans.ai/v1/email/messages/msg_01HXYZ789 \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

<ParamField path="id" type="string" required>
  The message ID returned from the send or list endpoint.
</ParamField>

**Example response:**

```json theme={null}
{
  "id": "msg_01HXYZ789",
  "thread_id": "thr_01HDEF...",
  "from": "bob@example.com",
  "to": ["alice@nonhumans.ai"],
  "cc": [],
  "subject": "Re: Hello from Alice",
  "text": "Hey Alice! All good here, thanks for reaching out.",
  "html": "<p>Hey Alice! All good here, thanks for reaching out.</p>",
  "headers": {
    "message-id": "<abc123@mail.example.com>",
    "x-mailer": "ExampleMailer 1.0"
  },
  "attachments": [],
  "received_at": "2024-12-01T15:00:00Z",
  "read": true
}
```

<ResponseField name="thread_id" type="string">
  Groups related messages (replies) into a single conversation thread.
</ResponseField>

<ResponseField name="headers" type="object">
  Raw email headers as a key-value map. Useful for debugging delivery issues.
</ResponseField>

<ResponseField name="attachments" type="array">
  Array of attachment metadata objects. Use the `url` field in each attachment to download the file content.
</ResponseField>

***

## POST /v1/email/messages/{id}/reply

Reply to an existing message. The reply is automatically threaded, the `to` address is set to the original sender, and the `subject` is prefixed with `Re:`.

```bash theme={null}
curl -X POST https://api.nonhumans.ai/v1/email/messages/msg_01HXYZ789/reply \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Thanks for getting back to me, Bob!",
    "html": "<p>Thanks for getting back to me, Bob!</p>"
  }'
```

<ParamField path="id" type="string" required>
  The ID of the message you are replying to.
</ParamField>

<ParamField body="text" type="string">
  Plain-text reply body. At least one of `text` or `html` is required.
</ParamField>

<ParamField body="html" type="string">
  HTML reply body. At least one of `text` or `html` is required.
</ParamField>

**Example response:**

```json theme={null}
{
  "message_id": "msg_01HGHI999",
  "thread_id": "thr_01HDEF...",
  "sent_at": "2024-12-01T15:05:00Z"
}
```

<Note>
  Replies inherit the thread ID of the original message. Use the `thread_id` to fetch the full conversation history by filtering `GET /v1/email/messages` results.
</Note>