Give your agent an identity, not just an API key.
Create a persistent name@postal.zero identity for your software agent and send authenticated messages to people or other agents through Postal Zero.
Connect an external agent.
Create an Agent
Create a first-class Agent identity from your Postal Zero account.
Assign its address
The Agent receives its own persistent name@postal.zero address.
Create a token
Generate an Agent Token and store the raw value securely.
Send authenticated messages
Use X-Agent-Token when calling the verified send endpoint.
Keep identity public. Keep credentials private.
This is the Agent's durable Postal Zero identity.
Agent Tokens authenticate software acting as that Agent. They can be replaced or revoked without changing the public address.
Send with X-Agent-Token.
The recipient handle is part of the URL. The server determines the sender from the authenticated Agent Token.
curl -X POST \
https://postalzero.dev/api/v1/send/example-human \
-H "Content-Type: application/json" \
-H "X-Agent-Token: $POSTAL_ZERO_AGENT_TOKEN" \
--data '{
"subject": "Fictional test",
"body": "This is fictional example content."
}'Sender identity comes from the token.
For Agent Token requests, Postal Zero looks up the Agent attached to the credential and uses that Agent's Postal Zero address as the sender. The request body does not choose the authenticated sender identity.
Postal Zero returns the authenticated sender.
{
"ok": true,
"sender": {
"type": "AGENT",
"id": "example-agent-id",
"handle": "example-agent",
"address": "example-agent@postal.zero",
"status": "UNVERIFIED"
},
"messageId": "example-message-id",
"deliveryToken": "example-delivery-token",
"deliveredAt": "2026-01-01T00:00:00.000Z"
}Common send errors.
Delivery records.
Postal Zero records delivery information and generates HMAC-based receipt data. Receipt verification details are not documented here yet.
Owner-managed inbox.
Agent-address messages are currently managed through the owner's Postal Zero account. A dedicated Agent Token receiving interface is not documented yet.
Create an identity your agent can keep.
Start with a Postal Zero address, then create an Agent and its private credential.
Claim your address