stuntman / providers / e-mail

E-mail

An SMTP server and a SendGrid v3 API that catch every message, extract codes and links, and play the recipient.

Stands in for

  • SMTP with STARTTLS
  • SendGrid v3 mail/send
  • SendGrid Event Webhook

Everything E-mail gives you

  1. 01

    Every message, kept

    HTML, text, headers and attachments of every message, filtered by recipient, subject, kind, language or inbox.

  2. 02

    Codes and links extracted

    Built-in code, links and attachments extractors, plus your own regex, CSS selector or header rules.

  3. 03

    Inboxes that decide

    An inbox accepts, bounces, defers N times, holds or drops what lands in it; temporary inboxes expire by themselves.

  4. 04

    Steps after delivery

    Inbox steps open the message or click a link after a wait, with jitter, so tests never wait for a person.

  5. 05

    Act as the recipient

    Open, click, spam report or unsubscribe sends SendGrid's Event Webhook, signed with ECDSA, to your app.

  6. 06

    Hold and decide

    A held message waits for you: deliver, defer, bounce hard or soft, or drop; the app gets the matching event.

  7. 07

    Strict or unreachable intake

    Validate keys (401, or 535 on SMTP), drop STARTTLS, refuse recipients with 550 or 451, or time out.

  8. 08

    Wait, or expect none

    wait_for_message returns the extracted value; expect_no_message passes only if nothing arrives in time.

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.

The message, and what was pulled out of it

The message, and what was pulled out of it: the E-mail screen in Stuntman
1Temporary inbox

A test made this address; it expires by itself in 18 min.

1 of 5
2How it came in

Via the SendGrid API or SMTP, with sender, recipient, time and trace.

2 of 5
3Extracted code

Your extractor found the OTP; wait_for_message with extract returns it.

3 of 5
4Links

Every link is detected; short links can be followed to the final URL.

4 of 5
5Events

Delivery and recipient events sent to the app's Event Webhook.

5 of 5
  1. Temporary inbox

    A test made this address; it expires by itself in 18 min.

  2. How it came in

    Via the SendGrid API or SMTP, with sender, recipient, time and trace.

  3. Extracted code

    Your extractor found the OTP; wait_for_message with extract returns it.

  4. Links

    Every link is detected; short links can be followed to the final URL.

  5. Events

    Delivery and recipient events sent to the app's Event Webhook.

An inbox decides what happens on arrival

An inbox decides what happens on arrival: the E-mail screen in Stuntman
1Temporary

Made by a test over the API; extend it or keep it with the environment.

1 of 5
2Bounce it

Hard bounce, 550 mailbox unavailable, as the provider's event.

2 of 5
3Defer N times

Defer 3 times, then accept: tests the app's retry.

3 of 5
4Hold it

Decide by hand with decide_held, or let the steps decide.

4 of 5
5Automatic steps

Delivered, opened 30 s later with 5 s of jitter, click signLink: no person needed.

5 of 5
  1. Temporary

    Made by a test over the API; extend it or keep it with the environment.

  2. Bounce it

    Hard bounce, 550 mailbox unavailable, as the provider's event.

  3. Defer N times

    Defer 3 times, then accept: tests the app's retry.

  4. Hold it

    Decide by hand with decide_held, or let the steps decide.

  5. Automatic steps

    Delivered, opened 30 s later with 5 s of jitter, click signLink: no person needed.

Extractors, tried before you save

Extractors, tried before you save: the E-mail screen in Stuntman
1Take it from

Subject, text, HTML, link, header or attachment.

1 of 5
2Rule

A regex, CSS selector or header name; a capture group becomes the value.

2 of 5
3Follow redirects

For short links: the value is the final URL.

3 of 5
4Against the last 50

test_extractor runs the rule on recent mail: matched, skipped, no such link.

4 of 5
5Why not

Messages where the rule found nothing, with the reason and a suggested fix.

5 of 5
  1. Take it from

    Subject, text, HTML, link, header or attachment.

  2. Rule

    A regex, CSS selector or header name; a capture group becomes the value.

  3. Follow redirects

    For short links: the value is the final URL.

  4. Against the last 50

    test_extractor runs the rule on recent mail: matched, skipped, no such link.

  5. Why not

    Messages where the rule found nothing, with the reason and a suggested fix.

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.

  • Bounce

    Hard or soft; the app gets the bounce event

    decide_held {action: bounce, kind: hard}
  • Defer, then accept

    The message is deferred N times before delivery

    create_inbox {on_arrival: defer, defer_times: 3}
  • Dropped

    The provider refuses to send it

    decide_held {action: drop}
  • Spam report

    The recipient marks it as spam; signed event to the app

    simulate_recipient {action: spamreport}
  • Unsubscribe

    The recipient unsubscribes; signed event to the app

    simulate_recipient {action: unsubscribe}
  • Provider unreachable

    The intake times out, refuses, or answers 503 or 429

    set_access {how: timeout}
  • TLS trouble

    SMTP without STARTTLS, or a TLS failure

    set_access starttls / how: tls
  • Recipients refused

    SMTP answers 550 or 451 to RCPT TO

    set_access {refuse_recipients: 550}
  • Revoked key

    Sends get 401, or 535 on SMTP, while keys are validated

    revoke_key

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

Test the password reset e-mail end to end and get me the reset link.

create_inbox{"prefix": "reset-test", "ttl": "2h"}
→ ok reset-test-a83f@stg-a.inbox.stuntman.dev, expires in 2 h
wait_for_message{"to": "reset-test-a83f@stg-a.inbox.stuntman.dev", "extract": "resetLink"}
→ ok https://acme-app.stg.example.com/reset/3f2c9e1a…

MCP tools

  • list_messagesMessages with filters, or grouped by kind
  • get_messageHeaders, text, HTML, extracted values, events
  • wait_for_messageWait for a message; with extract, return the value
  • expect_no_messagePass only if nothing arrives in time
  • create_inboxA temporary or kept inbox with its rule and steps
  • decide_heldDeliver, defer, bounce or drop a held message
  • simulate_recipientOpen, click, spam report or unsubscribe
  • test_extractorRun a rule on one message or the last N
  • set_accessMake the intake strict or unreachable

The same over HTTP

  • GET/api/messages
  • GET/api/messages/wait
  • POST/api/inboxes
  • POST/api/messages/{id}/decide
  • POST/api/messages/{id}/events