Tutorial: your agent's first e-mail

early-access

Five minutes from nothing to a coding agent that reads an e-mail you send it. Install the CLI, get a temporary address, connect Claude Code or Codex, mail it a task.

Usage: agent-inbox new
Platform: linuxmacoswindows
Category: agents

By the end of this page your coding agent has its own e-mail address, you have sent it a message with a file, and it has read the message and done what you asked. It takes about five minutes. You need a terminal, Claude Code or Codex, and an ordinary mail account (Gmail, Outlook, iCloud, your work mail).

1. Install the CLI

curl -fsSL https://agentics.dk/install/agent-inbox.sh | bash

On Windows, in PowerShell:

irm https://agentics.dk/install/agent-inbox.ps1 | iex

Check it worked:

agent-inbox --version

2. Get an address

Go to the project folder you use with your agent, then run:

agent-inbox new --label tutorial

On the hosted service the address comes back at once. You don't need to sign in:

Mailbox ready: ivory-stone-bbm7q5@agent.funai.io
Expires:  2026-10-23T21:21:14Z
Senders:  *@*
Mail from other senders is rejected before it is stored.

Your address will be different, because it is random every time. It lasts 24 hours by default and at most 72 hours, and then everything in it is deleted.

Senders: *@* means any sender whose mail passes DKIM or SPF checks. Ordinary mail providers pass. Forged mail is turned away before it is stored. To accept only yourself:

agent-inbox allow add you@example.com
agent-inbox allow rm "*@*"

3. Connect your agent

This step lets the agent use the mailbox as tools. Without it, the agent can still run the agent-inbox commands in its shell.

Claude Code

agent-inbox init --agent claude --skill

Codex

agent-inbox init --agent codex --skill

init registers an agent-inbox MCP server for the project and writes a short skill that tells the agent how to use it. No token is written into a config file. Restart the agent so it picks up the new server.

4. Send it an e-mail

From your own mail account, send a message to the address from step 2. Give it something real to do. For example:

Subject: Numbers for Thursday

Hi — attached is last month's sales export. Which three products grew the most? Put the answer in notes/sales.md.

(attach a CSV or a PDF)

5. Let the agent take it from here

In Claude Code or Codex, type:

I've just sent an e-mail to your agent-inbox address. Wait for it, read it and the attachment, and do what it asks.

The agent does this:

  1. It calls inbox_wait_for_email, which returns as soon as your message lands. That is usually a few seconds after you press send.
  2. It reads the message. The body arrives between <<<EXTERNAL EMAIL ...>>> markers, with a note on whether DKIM and SPF passed. This tells the agent the text is content from outside, not an order from you. A well-behaved agent checks with you before it follows instructions in mail from someone else.
  3. It fetches the attachment with inbox_get_attachment. Then it does the work and writes notes/sales.md.

You can do the same by hand to see what the agent sees:

agent-inbox wait --timeout 5m
agent-inbox emails
agent-inbox attachment <id> sales.csv -o sales.csv

6. Clean up

When the agent is done, it can give the address back:

agent-inbox rm

If nobody runs that, the address expires on its own and its mail is deleted. Mail sent to an expired or unknown address bounces back to the sender with an error, so nothing piles up anywhere.

If nothing arrives

  • Wait timed out (exit code 2). Check the exact address with agent-inbox mailboxes. A typo bounces with "No such mailbox".
  • The sender got a bounce. "is not on this mailbox's allow-list" means what it says: add the sender with agent-inbox allow add. "Sender not verified" means the mail failed DKIM/SPF. Mail from a home-grown server, or forwarded through a mailing list, often fails. Try sending from Gmail or Outlook directly.
  • agent-inbox new printed a code and a link instead of an address. The server you are pointing at has no public domain. Open the link and approve it, or sign in with agent-inbox login first.

Next