Mailboxes

A mailbox is a real email address your agents can read. You create one in the dashboard or through the API, pick a name, and any email sent to that address (for example example@agents.aiqaramba.com) is stored against the mailbox. You can then attach the mailbox to your agents to allow them to read the emails it receives.

Mailboxes are designed with simplicity in mind: an address, an inbox, and an attachment to a journey or test run. That simplicity is what makes them useful, because you can combine them however your tests need rather than work around a more opinionated abstraction.

Mailboxes are read-only. Your agents can pick up whatever lands in the inbox, but they cannot send mail from a mailbox. If you need an agent to send an outbound email as part of a test, that is outside what mailboxes do today.

How it works

There are three things to do:

  1. Create a mailbox. Pick a name. The full address you can hand to other systems is name@agents.aiqaramba.com. Names are unique across the entire platform on a first-come-first-served basis, so prefer something specific to you.
  2. Attach the mailbox to a journey or to an individual test run. Attachment is what grants the agent access to the inbox. A run with no attached mailbox cannot read any email at all; one with several attached mailboxes can read all of them.
  3. Run a test that needs email. An attached agent is told which mailbox addresses it has access to as part of its prompt, and can read the inbox at any point during the run. You can mention a specific address in your prompt or rely on the agent to pick the right attached mailbox itself when the flow calls for one.

Examples

Signup with email confirmation

A typical signup flow asks the new user to confirm their email address before they can log in. Without a mailbox the agent has no way to receive that email, and the test will stall on the “check your inbox” screen.

Create one mailbox per test identity you want to use, for example tester-acme, and attach it to your signup journey. You can either name the address explicitly in your prompt:

Sign up at https://app.example.com/signup using tester-acme@agents.aiqaramba.com as the email and any strong password. Then check your inbox, open the confirmation email, follow the verification link, and verify that you land on the dashboard logged in.

Or leave the address out and let the agent use the attached mailbox it has been given:

Sign up at https://app.example.com/signup using your attached mailbox address. Then open the confirmation email you receive, follow the verification link, and verify that you land on the dashboard logged in.

Password reset

Password reset is the same shape. If the account you are testing with already exists at tester-acme@agents.aiqaramba.com, attach that mailbox to the journey and write a prompt that walks through the reset:

Open https://app.example.com/login, click "Forgot password?", enter tester-acme@agents.aiqaramba.com, and submit. Then read the password reset email, follow the link, set a new password, and confirm you can log in with the new password.

Because the address is just the mailbox name plus the platform domain, the account on your side and the inbox on our side stay in sync forever. You do not have to coordinate test accounts and email aliases as two separate things.

Magic-link login

Magic-link auth is the cleanest fit. There is no password to remember and no test fixture to seed; the agent just enters the address, opens the email when it arrives, and clicks the link.

Log in at https://app.example.com/auth using your attached mailbox address. When the magic-link email arrives, open it and follow the link to finish signing in. Then verify the dashboard loads.

Organising your mailboxes

The platform does not impose any structure on how you use mailboxes, so there is no single right answer. A few patterns we see:

  • One mailbox per persistent test user. If your tests reuse the same accounts run to run, a mailbox per account is the simplest model. Old emails stick around so you can scroll back and see what the system was sending weeks ago.
  • One mailbox per environment. When you want strict separation between staging and production traffic, name them accordingly: tester-staging and tester-prod.
  • Shared mailboxes for collaboration. Anyone on your team attached to a journey gets the same view of the inbox, which makes it easy to debug a failing email-driven flow together.

When you no longer need a mailbox, deleting it drops every stored email and detaches it from any journey or test run that referenced it. The name is then free to be claimed again by anyone.