Skip to main content
AtomicMailTools give an agent its own email inbox: register an address on AtomicMail, send plain-text email from it, and read what it receives over JMAP. Registration runs through AtomicMail’s autonomous proof-of-work signup. There is no signup form, no domain setup, and no human verification step.

​
Prerequisites

No extra package is required beyond agno — the toolkit uses httpx, an Agno core dependency. The example also uses the openai library:
No AtomicMail API key is needed up front: register_inbox creates the account and stores the key it receives in credentials.json under ~/.atomicmail (override the directory with credentials_dir or the ATOMIC_MAIL_CREDENTIALS_DIR environment variable), so the same inbox is reused across agent runs. A credentials file that exists but cannot be read raises a ValueError instead of being overwritten with a fresh registration.

​
Example

The following agent registers an inbox and reads it. The first run solves the proof-of-work and takes tens of seconds; later runs reuse the stored credentials:

​
Proof-of-Work Sign-Up

AtomicMail issues inboxes to agents without a human step. Instead of a signup form, register_inbox requests a challenge and solves it locally — an scrypt computation whose difficulty AtomicMail sets server-side — then exchanges the solution for a session. AtomicMail uses this in place of CAPTCHAs and manual approval; see the AtomicMail docs for the protocol. Three things follow from that design:
  • The first call is slow. Expect register_inbox to take tens of seconds — AtomicMail quotes roughly 30 seconds. pow_timeout (default 300 seconds) caps the solve; a solve that exceeds it returns an error result instead of hanging.
  • The solve is parallel. pow_workers threads search the nonce space concurrently, defaulting to min(4, cpu_count()). Set pow_workers=1 to search sequentially.
  • Repeat calls are fast. Since Agno v3.0.4 the resolved session is cached on the toolkit instance until its token nears expiry, so warm send_email and list_inbox calls typically take roughly 0.4 to 3 seconds. A cold call — a new process, or an expired token — re-runs the handshake.
The inbox address is <username>@atomicmail.ai. Sending from your own domain requires verifying it in AtomicMail’s dashboard, outside the toolkit. AtomicMail publishes its storage quota and rate-limit policy in its documentation.

​
Toolkit Params

​
Toolkit Functions

Every function has an async variant registered under the same name, used automatically with arun and aprint_response. Failures come back as {"error": ...} results instead of raising to the model.

​
Developer Resources