> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Emails
> Give your agent a real inbox so it can send and receive email — useful for login codes, email-based 2FA, and email-driven workflows
Every agent profile in Asteroid is automatically provisioned with its own email inbox. Agents can read and send mail from this inbox during a run, which makes it easy to handle flows that depend on email — for example, retrieving a one-time login code, confirming a sign-up link, or replying to a counterpart.
Each agent profile gets its own address at `agentmail.asteroid.ai`
Override the default to use a friendly address like `acme-ops@agentmail.asteroid.ai`
Enable the `send_mail` and `get_mail` tools on AI Task nodes
Receive TOTP / login codes and feed them back into your workflow
## How the inbox is assigned
The inbox address is derived from the **agent profile** attached to the execution. The format is:
```
{prefix}@agentmail.asteroid.ai
```
By default the **prefix is the agent profile's UUID**, so a freshly created profile gets an address like:
```
9e2d8a14-3b1f-4e2c-9ab5-0c5f17d2c111@agentmail.asteroid.ai
```
You can override this by setting a custom **Inbox Email Prefix** on the profile (via the dashboard, API, or SDK). For example, setting the prefix to `acme-support` resolves to:
```
acme-support@agentmail.asteroid.ai
```
The prefix is normalised (lowercased and trimmed) and must be unique across the platform. If the prefix is already taken, profile creation/update will fail — pick a different one.
Inbox addresses are scoped to the agent profile, not the execution. Two executions that use the same profile (or two profiles in the same [profile pool](/fundamentals/profiles#profile-pools)) share an inbox. For strict isolation, give each agent its own profile.
## Requirements
To use email in an agent, two things have to be in place:
Email is a profile-bound feature. Executions without an agent profile (or pool) have no inbox, and the `send_mail` / `get_mail` tools will fail.
See [Agent Profiles](/fundamentals/profiles) for how to create one and how to attach it to an execution via the dashboard, API, or SDK.
On every AI Task node that needs to send or read mail, enable the email tools under the **Communication** capability in the node settings:
* `send_mail` — send an email from the profile's inbox
* `get_mail` — list recent emails, or fetch a specific email by ID
You can enable these in the graph editor (the **AI Capabilities** panel on the node) or, when configuring nodes programmatically, by listing them in the node's `tools` array. See [AI Capabilities → Communication](/fundamentals/ai-capabilities#communication).
## Configuring the prefix
1. Open **Agent Profiles** on the Asteroid platform.
2. Create a new profile, or open an existing one.
3. Set the **Inbox Email Prefix** field (e.g. `acme-support`).
4. Save. The full address is shown alongside the field.
Pass `inboxEmailPrefix` when creating or updating the profile.
See [Create an agent profile](/api-reference/agent-profiles/create-agent-profile) and [Update an agent profile](/api-reference/agent-profiles/update-agent-profile).
If you omit the field, the prefix defaults to the profile's UUID.
## Using email from an AI Task node
Once the tools are enabled and a profile is attached, the agent can call them like any other tool. The agent doesn't need to be told its own address — it's resolved automatically from the profile at runtime.
### Sending an email
The agent can send an email by calling `send_mail`. Typical instruction:
```
After you have generated the report, email a copy to {{.recipient}}:
- Subject: "Daily report for {{.account_name}}"
- Body: a short plain-text summary plus a link to the run
Use the send_mail tool. The "from" address is your inbox — you do not need to set it.
```
### Reading an email
The agent can list recent messages or fetch one by ID with `get_mail`. The tool only returns mail addressed to the profile's own inbox.
## Receiving email codes (OTP / login)
The most common use case for the inbox is **catching one-time codes** sent by email — for example, a login flow that emails a 6-digit verification code, or a magic-link sign-in.
The pattern is:
Instruct the agent to enter the profile's inbox address (e.g. `acme-support@agentmail.asteroid.ai`) into the sign-in form. You can pass the address in as a dynamic variable, or have the agent read it from the prompt.
Email delivery takes a few seconds. Tell the agent to **poll its inbox** rather than calling `get_mail` once — codes can arrive 5–30 seconds after the request.
Once the email is in the inbox, the agent extracts the code from the body and enters it into the verification field.
### Example prompt
```
Goal: Log into the {{.product_name}} dashboard. The site will email a 6-digit code to our inbox.
Steps:
1. Navigate to {{.login_url}}.
2. Enter the email address {{.agent_email}} into the email field and submit.
3. Wait for the verification email to arrive. It will be sent from "no-reply@{{.product_domain}}" with a 6-digit code in the body.
- Call get_mail to list recent emails.
- If the verification email is not present yet, wait ~10 seconds and call get_mail again.
- Retry up to 6 times (about a minute total) before giving up.
4. Once the email arrives, call get_mail with its email_id to fetch the full body.
5. Extract the 6-digit code from the body and enter it into the verification input on the page.
6. Click "Verify" and confirm you reach the dashboard.
Edge cases:
- If no email arrives after 6 polls, fail the task with a clear error message.
- Ignore unrelated emails (newsletters, marketing) — only act on the most recent verification email from the expected sender.
- If multiple verification emails are present, use the most recent one.
```
The verification code prompt above is generic — for password-based 2FA where the code comes from an **authenticator app** rather than email, use the built-in [TOTP tool](/fundamentals/profiles#2fa---totp-secrets) instead.
LLMs don't have a real `sleep` primitive — they "wait" by letting the next tool call happen on the next step of the loop. In practice, instructing the agent to "wait 10 seconds and retry" gives it enough latency in the model + tool round-trip to be effective. Avoid asking it to poll too tightly (e.g. every second) — it wastes steps and can hit rate limits on the upstream site.
## Privacy and isolation
* `get_mail` only returns emails addressed to the **profile's own inbox**. Mail sent to a different profile is not visible.
* Inbox addresses are unique across the platform — no two profiles can share the same prefix.
* Inboxes persist for the lifetime of the profile. Deleting the profile releases the prefix.
## Limitations
* The inbox is only available to executions that have an agent profile attached.
* Attachments on inbound mail are surfaced in the `get_mail` response but cannot currently be downloaded as workflow files.
* Mail delivery is best-effort — for hard-real-time flows, build in retries (see the prompt example above) rather than assuming the next `get_mail` call will succeed.
***
For more on profiles, credentials, and TOTP secrets, see [Agent Profiles](/fundamentals/profiles). For the full list of node capabilities including `send_mail` and `get_mail`, see [AI Capabilities](/fundamentals/ai-capabilities#communication).