stuntman / providers / mailboxes

Mailboxes

IMAP and POP3 mailboxes your app reads: put a supplier's invoice in, and the app finds it on its next poll.

Stands in for

  • IMAP4rev1
  • POP3
  • XOAUTH2 mail logins

Everything Mailboxes gives you

  1. 01

    Put mail in

    put_mail drops a message as if someone sent it: from, subject, text or HTML, attachments, or a whole raw RFC 822 message.

  2. 02

    Real IMAP commands

    SELECT, FETCH with BODYSTRUCTURE and sections, SEARCH, STORE, COPY, MOVE, EXPUNGE, IDLE and the UID commands.

  3. 03

    POP3 too

    STAT, LIST, UIDL, RETR, TOP and DELE over USER/PASS or AUTH PLAIN, with STLS.

  4. 04

    See what the app did

    Every command the app sent, with its time and without passwords, next to the messages it touched.

  5. 05

    Folders and flags

    INBOX first plus any folder; read and deleted flags show whether the app marked or removed what it read.

  6. 06

    Logins like the real thing

    LOGIN, AUTHENTICATE PLAIN and XOAUTH2 (any token); set a password per mailbox or let any password in.

  7. 07

    Mailbox trouble on cue

    A refused login, a mailbox in use, a connection dropped during FETCH, TLS required or an expired OAuth token.

The screens

Each number is a control or a reading on the real screen. Everything you can click there, your agent can do with a tool.

A mailbox the app reads

A mailbox the app reads: the Mailboxes screen in Stuntman
1Where to connect

IMAP on 1143 with STARTTLS, POP3 on 1110 with STLS.

1 of 5
2Mailboxes

Each address is a login; the count shows unread messages.

2 of 5
3Unread

The dot clears when the app sets \Seen; a PEEK fetch leaves it.

3 of 5
4Attachments

XML, PDF or images, as a supplier would attach them.

4 of 5
5Put the message

From, subject, text and an attachment; the app finds it on its next poll.

5 of 5
  1. Where to connect

    IMAP on 1143 with STARTTLS, POP3 on 1110 with STLS.

  2. Mailboxes

    Each address is a login; the count shows unread messages.

  3. Unread

    The dot clears when the app sets \Seen; a PEEK fetch leaves it.

  4. Attachments

    XML, PDF or images, as a supplier would attach them.

  5. Put the message

    From, subject, text and an attachment; the app finds it on its next poll.

What the app did, and what to break

What the app did, and what to break: the Mailboxes screen in Stuntman
1Put by you

Messages you or an agent put in, with their UID.

1 of 5
2The app's login

Each command is logged; passwords never are.

2 of 5
3How it fetched

BODY.PEEK[] leaves the message unread; the log shows which form the app used.

3 of 5
4Drop during FETCH

The connection closes mid-fetch: does the app retry without losing the message?

4 of 5
5XOAUTH2 token expired

The OAuth login is refused, as when a refresh is due.

5 of 5
  1. Put by you

    Messages you or an agent put in, with their UID.

  2. The app's login

    Each command is logged; passwords never are.

  3. How it fetched

    BODY.PEEK[] leaves the message unread; the log shows which form the app used.

  4. Drop during FETCH

    The connection closes mid-fetch: does the app retry without losing the message?

  5. XOAUTH2 token expired

    The OAuth login is refused, as when a refresh is due.

Break it on purpose

The failures you need to test, exactly when you ask: from the screen or by a tool call, each one shown on the timeline with who caused it.

  • Login refused

    Every login to the mailbox fails

    set_mailbox {provoke: login_refused}
  • Mailbox in use

    IMAP answers NO [INUSE]

    set_mailbox {provoke: busy}
  • Drop during fetch

    The connection closes during FETCH or RETR

    set_mailbox {provoke: drop_fetch}
  • TLS required

    Plain logins are refused before STARTTLS or STLS

    set_mailbox {provoke: tls_required}
  • Token expired

    XOAUTH2 logins are refused

    set_mailbox {provoke: token_expired}
  • Wrong password

    A login with the wrong password is refused

    set_mailbox {password} or the password "wrong"

Why not the real sandbox

Your AI agent drives it

Claude Code, Codex or any MCP client connects to /mcp (or calls /api over plain HTTP), sets the stand-in up, breaks it on cue and reads what your app did.

you

Check that our invoice importer picks up an XML attached to an e-mail.

put_mail{"address": "invoices@acme.example", "from": "billing@globex.example", "subject": "Invoice 1234", "attachments": [{"filename": "invoice-1234.xml", "content_type": "application/xml", "text": "<invoice/>"}]}
→ ok uid 3 in INBOX
list_mailbox_messages{"address": "invoices@acme.example"}
→ ok Invoice 1234 read; the app ran LOGIN, SELECT INBOX, SEARCH UNSEEN, FETCH 3

MCP tools

  • list_mailboxesMailboxes with messages, unread counts and how to connect
  • set_mailboxCreate or change a mailbox: password and provocation
  • put_mailPut a message in as if someone sent it
  • list_mailbox_messagesMessages, flags and the app's commands
  • get_environmentThe environment's addresses and settings
  • reset_environmentEvery service back to its seeds before a test

The same over HTTP

  • GET/api/mailboxes
  • PUT/api/mailboxes/{address}
  • POST/api/mailboxes/{address}/messages
  • GET/api/mailboxes/{address}/messages