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.

Per-profile inbox

Each agent profile gets its own address at agentmail.asteroid.ai

Custom prefix

Override the default to use a friendly address like [e-mail]

Send & receive

The send_mail and get_mail tools are always available to Agent nodes

Email 2FA

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:

[e-mail]

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:

[e-mail]

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) share an inbox. For strict isolation, give each agent its own profile.

Requirements

Email needs exactly one thing in place: an agent profile attached to the execution.

1. An agent profile is attached to the execution

   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 for how to create one and how to attach it to an execution via the dashboard, API, or SDK.

2. Nothing to enable on the node

   The email tools are always available to Agent nodes and activate automatically as soon as a profile — and therefore an inbox — is attached:

   • send_mail — send an email from the profile’s inbox
   • get_mail — list recent emails, or fetch a specific email by ID

   There is no capability toggle to switch on and nothing to list in the node configuration. Without a profile the tools are still exposed, but calling them returns an error.

Configuring the prefix

Dashboard

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.

API / SDK

Pass inboxEmailPrefix when creating or updating the profile.

See Create an agent profile and Update an agent profile.

If you omit the field, the prefix defaults to the profile’s UUID.

Using email from an Agent node

Once a profile is attached, the agent can call the email tools 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:

1. Submit the email address on the target site

   Instruct the agent to enter the profile’s inbox address (e.g. [e-mail]) into the sign-in form. You can pass the address in as a dynamic variable, or have the agent read it from the prompt.

2. Wait for the email to arrive

   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.

3. Extract the code and submit it

   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 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 — including the inbox each profile is provisioned with — see Agent Profiles.