> ## 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.

# Agent Email: Send & Receive Mail from Your Agent

> Your Nonhumans agent gets a real email inbox at name@nonhumans.ai. Send and receive messages via the SDK with no SMTP configuration required.

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

<CardGroup cols={2}>
  <Card title="Real Inbox" icon="inbox">
    A persistent mailbox at `name@nonhumans.ai` that accepts inbound messages from any sender on the internet.
  </Card>

  <Card title="Full Send/Receive" icon="paper-plane">
    Send rich HTML email, receive replies, and maintain threaded conversations — all via API.
  </Card>

  <Card title="Folder Navigation" icon="folder">
    Page through your inbox, sent folder, or any custom folder with cursor-based pagination for efficient retrieval.
  </Card>

  <Card title="Authenticated Delivery" icon="shield-check">
    SPF, DKIM, and DMARC are managed by the platform so your agent's outbound messages reach the inbox, not the spam folder.
  </Card>
</CardGroup>

## 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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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>",
  });
  ```

  ```python Python theme={null}
  import os
  from nonhumans import Nonhumans

  agent = Nonhumans(api_key=os.environ["NONHUMANS_API_KEY"])

  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>",
  )
  ```
</CodeGroup>

<ParamField body="to" type="string" required>
  Recipient email address.
</ParamField>

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

<ParamField body="text" type="string">
  Plain-text body. Recommended alongside `html` for maximum deliverability.
</ParamField>

<ParamField body="html" type="string">
  HTML body. Rendered by the recipient's email client.
</ParamField>

## 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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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,
    });
  }
  ```

  ```python Python theme={null}
  import os
  from nonhumans import Nonhumans

  agent = Nonhumans(api_key=os.environ["NONHUMANS_API_KEY"])

  messages = agent.email.list(
      folder="inbox",
      limit=20,
  )

  for msg in messages.data:
      print(msg.from_address, msg.subject, msg.received_at)

  # Fetch the next page
  if messages.cursor:
      next_page = agent.email.list(
          folder="inbox",
          limit=20,
          cursor=messages.cursor,
      )
  ```
</CodeGroup>

<ParamField body="folder" type="string">
  Folder to list. One of `inbox`, `sent`, `drafts`, or `trash`. Defaults to `inbox`.
</ParamField>

<ParamField body="limit" type="number">
  Maximum number of messages to return per page. Defaults to `20`, maximum `100`.
</ParamField>

<ParamField body="cursor" type="string">
  Pagination cursor returned from the previous response. Omit to start from the beginning.
</ParamField>

## 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.

<Tip>
  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.
</Tip>

## Rate Limits

| Limit                     | Value           |
| ------------------------- | --------------- |
| Outbound messages per day | 1,000 (default) |
| Recipients per message    | 50              |
| Inbound message retention | 90 days         |

<Note>
  Daily send limits can be increased for agents with a higher reputation score. Contact support or open a limit-increase request via the dashboard.
</Note>

<Warning>
  Do not store sensitive secrets (API keys, passwords) in email bodies. Emails are retained and searchable — use the [Credential Vault](/primitives/vault) instead.
</Warning>