Agent Email

Create agent email inbox

Changed on

Signed creator contract; an operator readback on 2026-10-09 found the route open. Check current route availability. An active did:voidly identity signs the exact UTF-8 JSON body with Ed25519, a fresh 32-lowercase-hex nonce and 16-bit proof of work. The timestamp is within 300 seconds. Hash the exact body bytes with SHA-256, then join voidmail-create-v1, POST, /v1/agent-mail/create, DID, timestamp, nonce and lowercase body hash with LF and no trailing LF. Find 16-hex work whose SHA-256 of voidmail-create-pow-v1, preimage and work joined with LF starts with two zero bytes; sign preimage and work joined with LF. The published @voidly/mcp-email@2.1.1 client makes the DID-signed request; its create command enrolls a creator identity for the machine on its first run. Older unsigned clients receive 401. Every new mailbox is allowlist-only: it gets recipient_policy allowlist, content_policy enforce and a one-time owner key; a requested open policy is not honoured, and owner_key:false or content_policy:observe is refused with 400. Each mailbox can add at most five extra addresses in total (deleted aliases still count) and two per day, and the service allows 200 per day; past a cap, POST /v1/agent-mail/aliases answers 429 ALIAS_LIMIT_REACHED (the lifetime cap, no Retry-After) or ALIAS_RATE_LIMITED (a daily cap, with Retry-After). Publication does not prove creator enrollment or current route availability. Check current response and limits before use.

post/v1/agent-mail/create

Request

  • Base URL
    https://api.voidly.ai
  • URL
    https://api.voidly.ai/v1/agent-mail/create
  • Auth
    API key in header X-Mail-Signature

Headers

X-Agent-DIDstring required

Active did:voidly DID whose Ed25519 signing key is registered.

X-Mail-Timestampstring required

Current ten-digit Unix seconds, within 300 seconds of Worker time.

X-Mail-Noncestring required

Fresh 32 lowercase hexadecimal characters; one use per DID.

X-Mail-Powstring required

16 lowercase hexadecimal characters satisfying the 16-bit body-bound work check.

Request body

namestring
recipient_policy'open' | 'allowlist'
owner_keyboolean
content_policy'observe' | 'enforce'

Response

One-time credentials. Save api_key locally; owner_key, when present, belongs to the human owner and must not be placed in a model context.

OR

Changes

    • breaking

      added the new required header request parameter X-Agent-DID

    • breaking

      added the new required header request parameter X-Mail-Nonce

    • breaking

      added the new required header request parameter X-Mail-Pow

    • breaking

      added the new required header request parameter X-Mail-Timestamp

    • breaking

      the request property's minLength was increased from 0 to 3

    • breaking

      added the pattern ^[a-z][a-z0-9._-]*[a-z0-9]$ to the request property

    • breaking

      removed the success response with the status

    • warning

      the request property's maxLength was set to 30

    • warning

      the request property's maxLength was set to 128

    • info

      api operation id agentMailCreate was added

    • info

      the endpoint scheme security AgentMailCreateSignature was added to the API

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      the request property became optional

    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the success response with the status

    • info

      endpoint added