Reference

Email Addresses

How an inbound email maps to a wake: the address format, what is validated, what is metered, and why it is a one-way trigger.

Addressing scheme

Each agent is addressable on the dedicated mail domain mail.wakeup.sh. The canonical form is dot delimited:

<agent>.<handle>@mail.wakeup.sh

# example: handle "matt", agent "conductor"
conductor.matt@mail.wakeup.sh

The local part is parsed by splitting on the final dot: everything after it is the handle, everything before it is the agent name. This is unambiguous because handles and agent names match ^[a-z][a-z0-9_]{1,38}[a-z0-9]$ and therefore never contain a dot.

Plus addressing (RFC 5233 subaddressing) is also accepted and resolves to the same agent:

<handle>+<agent>@mail.wakeup.sh

# example
matt+conductor@mail.wakeup.sh

Some external senders mangle the plus character, so the dot delimited form is the default and the recommended one to publish. Use plus addressing only where you control the sender or forwarding rule.

Entitlement

An email address exists only for agents with a public address, that is, on an active Pro or Team plan. A Free agent is not publicly reachable and has no email address; mail to it is rejected at the gateway. Archived accounts are rejected as well.

Metering

An inbound email is an inbound external event hitting your agent, structurally the same as a web wake and traveling the same relay. It counts as one wake against your monthly allowance, shared with web wakes. The wake is consumed before the task is dispatched; if you are over your allowance the message is rejected and no task is created. Local cron and same machine agent-to-agent remain free and are never metered.

Inbound message shape

The MIME message is parsed into a standard A2A user message:

A leading text part carrying the subject and the plain text (or HTML) body. If the body is very large it is stored by reference instead of inlined.
One part per attachment, each a reference of the form { url, mediaType, filename } pointing at the stored blob, not inline bytes.
Metadata with source: "email", the original from, and the subject.

{
  "role": "user",
  "parts": [
    { "text": "Subject: <subject>\n\n<body>" },
    { "url": "r2://email/<agentId>/<messageId>/attachments/0", "mediaType": "application/pdf", "filename": "jd.pdf" }
  ],
  "metadata": { "source": "email", "from": "sender@example.com", "subject": "<subject>" }
}

Sender validation & dedupe

SPF, DKIM, and DMARC are checked on arrival. A message that fails authentication is rejected before any task is created, so a spoofed sender cannot wake your agent.
Message-ID dedupe. Providers retry delivery; a repeated Message-ID is treated as the same message and processed at most once.

Size limits

Inbound messages are capped at 25 MiB by the mail gateway. Attachments and oversized bodies are written to blob storage and passed to your agent by reference rather than streamed inline, so a large message never blocks the relay. Your command fetches a referenced part only if it needs the bytes.

One-way trigger

Email is a one-way trigger. The SMTP acceptance of the inbound message is the only acknowledgment — no reply or receipt is ever sent back to the sender. The message wakes the agent and the task runs the full lifecycle; its result is available over A2A (tasks/get, streaming, or push notifications), not by email. If your command needs to notify someone, it sends that itself through its own channel.