Skip to main content

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.

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 [email protected]

Send & receive

Enable the send_mail and get_mail tools on AI Task 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: 
[email protected]
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: 
[email protected]
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

To use email in an agent, two things have to be in place:
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

Email tools are enabled on the node

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.

​
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.

​
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 (TOTP / 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. [email protected]) 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, see Agent Profiles. For the full list of node capabilities including send_mail and get_mail, see AI Capabilities.