Skip to main content

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.

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>"
  }'
​
to
string[]
required
Array of recipient email addresses.
​
cc
string[]
Array of CC email addresses.
​
bcc
string[]
Array of BCC email addresses. Recipients are hidden from each other.
​
subject
string
required
Email subject line. Maximum 998 characters.
​
text
string
Plain-text body of the email. At least one of text or html is required.
​
html
string
HTML body of the email. At least one of text or html is required.
​
attachments
array
Array of attachment objects.
Example response: 
{
  "message_id": "msg_01HXYZ789",
  "sent_at": "2024-12-01T14:30:00Z"
}
​
message_id
string
Unique identifier for the sent message. Use this to retrieve or reply to the message later.
​
sent_at
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"
​
folder
string
Mailbox folder to query. One of inbox, sent, drafts. Defaults to inbox.
​
limit
integer
Number of messages to return. Default 20, max 100.
​
cursor
string
Pagination cursor from a previous response’s next_cursor.
​
since
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"
​
id
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
}
​
thread_id
string
Groups related messages (replies) into a single conversation thread.
​
headers
object
Raw email headers as a key-value map. Useful for debugging delivery issues.
​
attachments
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>"
  }'
​
id
string
required
The ID of the message you are replying to.
​
text
string
Plain-text reply body. At least one of text or html is required.
​
html
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.