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

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.

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

string[]

required

Array of recipient email addresses.

string[]

Array of CC email addresses.

string[]

Array of BCC email addresses. Recipients are hidden from each other.

string

required

Email subject line. Maximum 998 characters.

string

Plain-text body of the email. At least one of text or html is required.

string

HTML body of the email. At least one of text or html is required.

array

Array of attachment objects.

Show Attachment fields

string

required

Name of the attached file as it will appear to the recipient.

string

required

Base64-encoded file content.

string

required

MIME type of the attachment (e.g. application/pdf, image/png).

Example response:

{
  "message_id": "msg_01HXYZ789",
  "sent_at": "2024-12-01T14:30:00Z"
}

string

Unique identifier for the sent message. Use this to retrieve or reply to the message later.

string (ISO 8601)

Timestamp when the message was accepted for delivery.

GET /v1/email/messages

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

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

string

Mailbox folder to query. One of inbox, sent, drafts. Defaults to inbox.

integer

Number of messages to return. Default 20, max 100.

string

Pagination cursor from a previous response’s next_cursor.

string (ISO 8601)

Only return messages received or sent after this timestamp.

Example response:

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

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

curl https://api.nonhumans.ai/v1/email/messages/msg_01HXYZ789 \
  -H "Authorization: Bearer $NONHUMANS_KEY"

string

required

The message ID returned from the send or list endpoint.

Example response:

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

string

Groups related messages (replies) into a single conversation thread.

object

Raw email headers as a key-value map. Useful for debugging delivery issues.

array

Array of attachment metadata objects. Use the url field in each attachment to download the file content.

POST /v1/email/messages//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:.

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

string

required

The ID of the message you are replying to.

string

Plain-text reply body. At least one of text or html is required.

string

HTML reply body. At least one of text or html is required.

Example response:

{
  "message_id": "msg_01HGHI999",
  "thread_id": "thr_01HDEF...",
  "sent_at": "2024-12-01T15:05:00Z"
}

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.

Overview

Endpoints

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

POST /v1/email/send

GET /v1/email/messages

GET /v1/email/messages/

POST /v1/email/messages//reply

​POST /v1/email/send

​GET /v1/email/messages

​GET /v1/email/messages/

​POST /v1/email/messages//reply

POST /v1/email/send

GET /v1/email/messages

GET /v1/email/messages/

POST /v1/email/messages//reply