---
title: "Mail"
description: "Real email for agents — sending, receiving, threading, drafts, attachments, domains, and contacts."
canonical_url: "https://www.agent-identity.dev/docs/mail"
markdown_url: "https://www.agent-identity.dev/docs/mail.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
---

# Mail
URL: /docs/mail
LLM index: /llms.txt
Description: Real email for agents — sending, receiving, threading, drafts, attachments, domains, and contacts.
Related: /docs/mail/sending, /docs/mail/receiving, /docs/mail/domains

# Mail

Every agent gets a mailbox when it is created, at
`<handle>@<your-sending-domain>`. It is a real address: it sends, it receives, it threads
replies, and it carries attachments.

- **[Sending](/docs/mail/sending)** — the send endpoint, idempotency, and delivery status.
- **[Receiving](/docs/mail/receiving)** — the inbound webhook, signature verification, and
  thread correlation.
- **[Drafts](/docs/mail/drafts)** — compose now, send later, useful when a human approves
  what the agent wrote.
- **[Attachments](/docs/mail/attachments)** — base64 in, bytes or redirect out.
- **[Domains](/docs/mail/domains)** — verifying your own sending domain, and the SPF/DKIM/
  DMARC records that decide whether anything lands.
- **[Contacts](/docs/mail/contacts)** — the address book, and allow/block rules.

## Threads

Messages belong to threads. Outbound messages start one or continue one via
`in_reply_to_message_id`. Inbound messages are correlated by their `In-Reply-To` and
`References` headers, falling back to subject matching within the mailbox.

```bash title="terminal"
curl -sS "https://api.agent-identity.dev/v1/identities/$AID_AGENT/mail/threads/$THREAD_ID" \
  -H "authorization: Bearer $AID_KEY"
```

Returns the thread's subject and every message in it, in order — which is usually what
you want to hand an LLM as conversation context.

## Status

An outbound message moves through `queued` → `sent` → `delivered`, or lands on `bounced`
or `complained`. Each transition appends an [event](/docs/concepts/events), so an agent
can wait on `mail.bounced` rather than re-reading the message row.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).