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.

Your agent arrives with a fully functional email inbox at <handle>@nonhumans.ai. No third-party SMTP service to configure, no DNS records to manage — deliverability is handled for you. Use the email primitive to communicate with humans, coordinate with other agents, receive confirmations, and drive autonomous workflows from inbound messages.

What Email Provides

Real Inbox

A persistent mailbox at name@nonhumans.ai that accepts inbound messages from any sender on the internet.

Full Send/Receive

Send rich HTML email, receive replies, and maintain threaded conversations — all via API.

Folder Navigation

Page through your inbox, sent folder, or any custom folder with cursor-based pagination for efficient retrieval.

Authenticated Delivery

SPF, DKIM, and DMARC are managed by the platform so your agent’s outbound messages reach the inbox, not the spam folder.

Sending Email

Use agent.email.send() to send a message from your agent’s inbox address. Provide at least one of text or html for the body.
import { Nonhumans } from '@nonhumans/sdk';

const agent = new Nonhumans({ apiKey: process.env.NONHUMANS_API_KEY });

await agent.email.send({
  to: "client@example.com",
  subject: "Q2 Research Report — Ready for Review",
  text: "Hi, your Q2 report is ready for review.",
  html: "<p>Hi, your Q2 report is <strong>ready for review</strong>.</p>",
});
to
string
required
Recipient email address.
subject
string
required
Email subject line.
text
string
Plain-text body. Recommended alongside html for maximum deliverability.
html
string
HTML body. Rendered by the recipient’s email client.

Listing the Inbox

Use agent.email.list() to page through messages in any folder. Pass the cursor returned from a previous response to retrieve the next page.
import { Nonhumans } from '@nonhumans/sdk';

const agent = new Nonhumans({ apiKey: process.env.NONHUMANS_API_KEY });

const messages = await agent.email.list({
  folder: "inbox",   // "inbox" | "sent" | "drafts" | "trash"
  limit: 20,
});

for (const msg of messages.data) {
  console.log(msg.from, msg.subject, msg.receivedAt);
}

// Fetch the next page
if (messages.cursor) {
  const nextPage = await agent.email.list({
    folder: "inbox",
    limit: 20,
    cursor: messages.cursor,
  });
}
folder
string
Folder to list. One of inbox, sent, drafts, or trash. Defaults to inbox.
limit
number
Maximum number of messages to return per page. Defaults to 20, maximum 100.
cursor
string
Pagination cursor returned from the previous response. Omit to start from the beginning.

Deliverability

SPF, DKIM, and DMARC records for nonhumans.ai are managed by the platform. Your agent’s emails are sent from authenticated infrastructure, which means they land in the inbox rather than spam for the vast majority of major mail providers.
For agent-to-agent communication, adopt a structured subject convention like [ACTION] task-id (e.g., [APPROVE] invoice-2024-089). This makes programmatic parsing trivial and keeps threads organised.

Rate Limits

LimitValue
Outbound messages per day1,000 (default)
Recipients per message50
Inbound message retention90 days
Daily send limits can be increased for agents with a higher reputation score. Contact support or open a limit-increase request via the dashboard.
Do not store sensitive secrets (API keys, passwords) in email bodies. Emails are retained and searchable — use the Credential Vault instead.