Setting up Cofactor agents to receive email

Let your tests read the email your application sends — sign-in codes, magic links, invitations, password resets, notifications. Cofactor gives a test account its own mailbox on @testuser.runcofactor.com; mail your app sends to that address is captured, and the agent reads it during a run.

• A mailbox per account — every credential can have an inbox address; seeded users get a fresh one on every run.
• Sender allow list — only mail from domains you approve is delivered, so a mailbox can't be spammed or spoofed.
• Agent reads it — a step that says "open the verification email and use the code" just works; the agent searches, waits for, and reads the message itself.

01Give the account a mailbox

Every mailbox is tied to a credential. Three ways to get one:

The credentials list shows an Email inbox badge on every credential that has one. Your application must know that address — it's the email you register, invite, or send to. See Credentials and login for the credential side.

02Allow your sender domain

Cofactor only delivers mail whose sender is on your organization's allow list. Everything else is dropped, silently, before it reaches a mailbox.

1. Open the application and go to its Messages tab.
2. Under Allow a sender domain, enter the domain your app sends from and add it.

Rules for the list:

• Exact match, one entry per domain. myapp.com does not cover mail.myapp.com or notifications.myapp.com — add each domain your app sends from.
• Both the visible From address and the envelope sender count. Mail is delivered if either is on the list. Email providers often use a separate bounce/envelope domain (for example em1234.myapp.com or the provider's own domain) — if mail isn't arriving, check the raw headers of a real message and add that domain too.
• Matching is case-insensitive.

The sender domain is the domain in your app's outgoing mail, not the testuser.runcofactor.com domain of the mailbox.

03Write the step

Describe what to read and what to do with it — the agent has an inbox tool scoped to the credential in use and handles searching, waiting for delivery, and opening the message:

• "Open the verification email sent to $var.new_user.username and enter the 6-digit code."
• "Follow the Accept invitation link from the most recent email."
• "Wait for the password-reset email, open the reset link, and set the password to $var.new_user.password."

Don't hard-code a code or link in the step's inputs — it changes every run. If a login flow itself needs a code (OTP, magic link), select a credential with a paired inbox and the login handles it; see Credentials and login.

04See what arrived

The application's Messages tab lists every message delivered to its mailboxes — filter by mailbox, search subject or body, and open a message to see what the agent saw. Use it to confirm delivery before blaming the step.

05Troubleshooting

06Related

• Credentials and login
• Seeding a fresh test user
• Personas