ASMTP

ASMTP is mail for agents.

Every agent owns a server-held mailbox. To send, you drop an envelope in the recipient's mailbox. To receive, you read your own. The network handles delivery; the receiver writes only content.

ASMTP is the Agent Simple Mail Transfer Protocol: a small open specification for asynchronous, mailbox-shaped, context-economical communication between AI agents. Successor to ASP; identity and trust inherited from ASP unchanged.

Read the whitepaper | View on GitHub

Diagram of two agents exchanging an envelope through an ASMTP mailbox
Send drops an envelope into the recipient's mailbox. Headers push; bodies fetch.

Five wire primitives

PrimitiveRole
MailboxPer-agent durable inbox. Outlives every runtime.
EnvelopeWire message: id, from, to, subject, content parts.
Push frameHeaders only. The body is fetched on demand.
CursorWhat you have been notified about. Replay-safe across reconnects.
MonitorOpt-in sender-side delivery facts. Receiver emits nothing.

An agent is not a service. It is a contractor.

A service holds an open port and answers RPCs on demand; it lives in a process that must keep running for it to mean anything. A contractor lives at an address. Work arrives in a mailbox, is handled when they are next active, and the messages they have not gotten to remain waiting. ASMTP is built for the second model.

Both online: the happy path

Sender POSTs an envelope. The operator stores it durably and returns 202. The recipient's WebSocket receives a header-only push frame (typically ~80 tokens). The recipient decides whether to open the body and fetches it via REST.

POST /messages (envelope)store(envelope)202 storedpush frame (headers only)GET /messages/{id}full envelopeSenderOperatorMailboxRecipient
Mermaid source
sequenceDiagram
  participant S as Sender
  participant Op as Operator
  participant Mb as Mailbox
  participant R as Recipient
  S->>Op: POST /messages (envelope)
  Op->>Mb: store(envelope)
  Op-->>S: 202 stored
  Op->>R: push frame (headers only)
  R->>Op: GET /messages/{id}
  Op-->>R: full envelope

Receiver offline: the async case

The recipient's harness is closed. The envelope sits in the durable mailbox. When the recipient next comes online, it subscribes with its persisted cursor and the operator replays the headers it missed. Nothing is lost; no timeouts fire.

POST /messagesstore(envelope)202 storedWS subscribe (cursor=N)replay headers since NGET /messages/{id}full envelopeSenderOperatorRecipient mailboxRecipient
Mermaid source
sequenceDiagram
  participant S as Sender
  participant Op as Operator
  participant Mb as Recipient mailbox
  participant R as Recipient
  S->>Op: POST /messages
  Op->>Mb: store(envelope)
  Op-->>S: 202 stored
  Note over R: harness offline for hours
  R->>Op: WS subscribe (cursor=N)
  Op-->>R: replay headers since N
  R->>Op: GET /messages/{id}
  Op-->>R: full envelope

Headers cheap, bodies opt-in

Context economy is a first-class property of the protocol. A push frame is ~80 tokens; a typical body is 500 to 5,000+. Headers are 1 to 4% the cost of bodies. An agent waking to 84 unread envelopes pays ~6,700 tokens of headers and triages the lot in one model turn, rather than absorbing ~80,000+ tokens of bodies whether it needs them or not. The same opt-in pattern is what makes agent skills work at scale.

What ships in the repo