Skip to main content
Every agent profile owns an email inbox. A workflow attached to that profile can read and send mail during an execution. The inbox exists for work that email gates:
  • Login codes — a site emails a one-time code before it lets the workflow in.
  • Email two-factor — a verification step that goes to an address instead of an authenticator app.
  • Magic links — a sign-in flow that sends a link rather than a password.
  • Email-driven work — send a finished report, confirm a sign-up, reply to a counterpart.

​
The address

The address comes from the profile, and its shape is fixed:
The default prefix is the profile’s UUID. A new profile gets an address like this:
Set an Inbox Email Prefix on the profile to get a readable address. A prefix of acme-support resolves to:
Set the prefix on the platform, or pass inboxEmailPrefix when you create or update the profile.
Asteroid lowercases and trims the prefix. Every prefix is unique across the platform. If the prefix is taken, the profile save fails. Pick another one.

​
What the workflow needs

The inbox needs one thing: a profile attached to the execution. Agent nodes always carry two email tools: There is nothing to switch on. The tools work as soon as a profile is attached. An execution without a profile has no inbox, and both tools return an error. The workflow does not need to be told its own address. Asteroid resolves it from the profile at runtime.

​
Scope and isolation

The inbox belongs to the profile, not to the execution.
  • get_mail returns mail addressed to the profile’s own inbox only. Mail for another profile stays invisible.
  • Two executions on the same profile share one inbox.
  • The inbox lives as long as the profile. Deleting the profile releases the prefix.
For strict separation between workflows, give each workflow its own profile.

​
Limits

  • The inbox is available to runs with an attached profile only.
  • An attachment on inbound mail appears in the get_mail response, but you cannot download it as a workflow file.
  • Delivery is best-effort. A code can land 5–30 seconds after the request.
Because delivery takes time, instruct the workflow to poll its inbox rather than call get_mail once. Tell it how long to wait between tries and when to give up. See Write good instructions.
For a code from an authenticator app, store a TOTP secret on the profile instead. See Agent profiles.

Agent profiles

Where the inbox and the credentials live

Write good instructions

Tell the workflow how to poll for a code