Every reachable agent gets a public email address. Anything that can send an email can wake your agent.
An inbound email to your agent becomes a wake: a task on the exact same A2A lifecycle as a message/send call, relayed down to your local daemon and dispatched to your command. The subject, body, and attachments arrive as the task message. Email is a one-way trigger — successful delivery is the acknowledgment, and no reply is sent back.
You never give wakeup access to your inbox. You point a forwarding rule, a notification, or a job alert at the address, and each message that arrives turns into one task. No OAuth, no mailbox scopes.
Your agent's address is its name, then your handle, on the wakeup mail domain. For handle @matt and agent conductor:
conductor.matt@mail.wakeup.shThe local part is agent.handle, split on the final dot. Agent names and handles never contain a dot, so the address is always unambiguous. A plus-addressed form, matt+conductor@mail.wakeup.sh, also works for senders you control. See the Email Addresses reference for the full scheme.
Email comes with a public address, so it is available on the plans that make an agent reachable (Pro and Team). A Free agent has no public address and therefore no email address. Run wakeup upgrade to make an agent reachable, then it can receive email immediately. There is nothing to configure per address.
Each inbound email counts as one wake against your monthly allowance, exactly like an inbound web call. See Plans & tiers.
The email is turned into a standard A2A message. The subject and body become a text part; each attachment becomes a part referenced by URL (large content is stored out of band rather than inlined). The original sender and subject are preserved in the message metadata so your command can route on them.
{
"taskId": "b2c3...",
"contextId": "a1f0...",
"message": {
"role": "user",
"parts": [
{ "text": "Subject: New role: Staff Engineer\n\nA job matching your alert was posted..." },
{ "url": "r2://email/<agent>/<msg>/attachments/0", "mediaType": "application/pdf", "filename": "jd.pdf" }
],
"metadata": { "source": "email", "from": "alerts@jobboard.example", "subject": "New role: Staff Engineer" }
}
}Email wakes use the same dispatch path as every other task, so your command does not need to know it came from email. The hydrated transform_template gives you the text directly, or read the full task JSON from stdin (including metadata.source) for finer control.
# ~/.wakeup/config.yaml
agents:
conductor:
workspace: "/Users/you/projects/conductor"
command: "claude -p"
transform_template: |
An email arrived from {{data.from}}.
{{message.text}}
Decide whether it needs action and act on it.See Building Agents for how tasks are passed to your command and how responses are read, and the Config Reference for every template token.
Email is a one-way trigger: a message wakes your agent, and that is the whole interaction. Successful delivery (the SMTP acceptance) is the acknowledgment — wakeup never sends a reply or a receipt back to the sender.
If your command needs to notify someone, send that from the command itself through whatever channel you choose (your own email provider, Slack, a webhook). The task still runs the full lifecycle, so its status and any artifacts remain available over A2A (tasks/get, streaming, or push) — email just isn't the return path.