USE CASES

One mail pipeline, three front doors

A disposable address you click into, a REST API your test suite asserts on, and a clean tool surface for your AI agent. Same ingestion, same parsed message, same tenancy.

THE THREE SURFACES

Pick the door, not the product

Every surface resolves the same address, writes through the same persistence path, and reads the same parsed message. What changes is who is holding it and how they authenticate.

UC-1
IN DESIGN
Disposable inbox

“I need an email address for the next four minutes.”

WHO
A signed-in user who needs a throwaway address now
ENTRY
Dashboard, one click
AUTH
Session — account required
LIFETIME
Minutes to days, user-chosen
See the flow →
UC-2
AVAILABLE
Email-testing API

“My test suite needs to assert on a real verification email.”

WHO
Developers, QA engineers, CI
ENTRY
/v1 REST, webhooks, POP3/IMAP
AUTH
Project API key, live or test
LIFETIME
Ephemeral TTL or persistent mailbox
See the flow →
UC-3
IN DESIGN
AI agents as clients

“Verify the signup flow works end to end.”

WHO
Your agent — MailHulk ships none of its own
ENTRY
MCP server → /v1
AUTH
Scoped, expiring agent credential
LIFETIME
Session-scoped
See the flow →
AT A GLANCE
UC-1 · Disposable
UC-2 · Testing API
UC-3 · AI agents
Job to be done
Get a code out of a service I don't want in my real mailbox
Assert on real mail in an automated test
Complete an email flow autonomously
Writes code?
No
Yes
The agent does
Address shape
<local>@<project>.mailhulk.net
Same, or your custom domain
Same
Comparable to
YOPmail, temp-mail
Mailosaur
An emerging category
They are the same product underneath

UC-1 is not a separate system — it is a dashboard front end over the ephemeral inbox UC-2 already provides. UC-3 is not a separate API — it is /v1 with agent-shaped ergonomics and tighter credentials. One ingestion path, one parser, one tenancy model.

UC-1 · DISPOSABLE INBOX

An address for the next four minutes

One-off and manual by definition. Writing a test would cost more than doing it by hand — so the whole surface is tuned for the fifteen seconds between “I need an address” and “here is my code”.

WHO IT IS FOR
Developer, off-task
Sign up to a competitor, a vendor trial, or a docs site without handing over a real address
QA engineer, exploratory
Reproduce a customer's signup by hand before deciding whether it's worth automating
Support engineer
See what a customer actually received — the real rendered email, not a template preview
Designer / PM
Check how an onboarding email looks in a real inbox, on a phone
1
New disposable address

One click generates a pronounceable local part on your project's namespace — brisk-otter-41@acme-staging.mailhulk.net — shown large, with a copy button and a QR code. Overwrite it with something typeable if you prefer.

2
Pick a lifetime

10 minutes · 1 hour · 24 hours · 7 days, capped by your plan's retention. Add a note — “Figma trial” — so tomorrow's you knows what it was for.

3
Paste it and watch

The inbox view streams. “Waiting for mail…” becomes the message itself, with no refresh and no polling loop of your own.

4
Copy the code

The viewer shows sender, subject, time, rendered HTML, a text toggle, attachments, raw source — and the extracted links and codes with a copy button beside each one.

5
Forget about it

The address expires on its own and releases its inbox slot. Nothing to clean up, no cron job, no leftover state.

Account-bound, on purpose

There is no anonymous public inbox. On a temp-mail site the address is the credential — anyone who guesses it reads your mail. Here a disposable address is readable only by members of its project, so there is no enumeration surface, no anonymous flood to rate-limit by IP, and abuse always has a team attached. It also means your teammates can pick up the same inbox.

What it deliberately does not do

Receive-only — no sending, replying, or forwarding to a real mailbox from a disposable address; a relay is an abuse surface. No aliases or routing rules. No reserved local parts such as postmaster@ or abuse@ — platform mail must not be interceptable.

WHEN THINGS GO SIDEWAYS
SITUATION
BEHAVIOR
Follow a link instead of a code
Extracted links are listed; clicking one shows a confirmation interstitial with the destination host, referrer stripped. Deliberate friction on the one risky action.
Come back tomorrow
The address is in Inboxes → Disposable, listed with time-to-expiry, message count, and its note.
Need it longer
Extend before expiry. The expiry is re-stamped, still capped by plan retention.
Done early
Destroy the address; its messages go with it immediately rather than waiting out plan retention.
Someone else's inbox
Anyone outside the project gets a 404. Resource existence never leaks.
You're doing this a lot
The view shows the same parsed JSON a /v1 capture returns, with a copyable curl beside it. That is the on-ramp to the API.
UC-2 · EMAIL-TESTING API

Assert on real mail, from CI

The commercial core. A fresh inbox per test case, a blocking wait instead of a sleep, and content that arrives already parsed — because MIME handling in test code is where the brittleness used to live.

THE CANONICAL FLOW

Ephemeral inbox per test

Create an inbox, trigger your app, block until the mail lands, assert on the parsed content, and let the TTL clean up after you — even if the test crashes before it can delete anything.

Fresh inbox per run — no pooled cross-talk
?wait= long-poll, not sleep-and-hope
Links, codes, bodies and attachments pre-parsed
Idempotency-Key — a CI retry can't double-create
Additive-only within v1
curl
Node.js
Python
# 1. fresh inbox, self-cleaning
INBOX=$(curl -sS -X POST "$MAILHULK/v1/inboxes" \
-H "Authorization: Bearer $MH_KEY" \
-H "Idempotency-Key: $CI_RUN-signup" \
-d '{"name":"signup-test","ttl_seconds":900}')
 
# 2. your app sends to $ADDRESS …
 
# 3. block until it lands — no polling loop
MSG=$(curl -sS "$MAILHULK/v1/inboxes/$ID/messages/latest?wait=60" \
-H "Authorization: Bearer $MH_KEY")
 
# 4. assert on parsed content — never raw MIME
echo "$MSG" | jq -r '.codes[0]' # "481902"
echo "$MSG" | jq -r '.links[0]' # "https://app.example.com/verify/…"
THE OTHER FLOWS
»
Webhook push
Register an endpoint and MailHulk POSTs the fully parsed message, HMAC-signed, retried with backoff, with a delivery log and manual resend.
@
Persistent mailbox
A stable address such as support@acme.com on a verified custom domain — for nightly regression sweeps rather than a fresh inbox per test.
::
POP3 / IMAP
Every inbox response carries host, port and credentials. Point Thunderbird, an ERP, or any legacy system straight at it.
DNS
Custom domain
Add a domain, follow the copy-ready DNS guide, auto-verify, then address mail on it — one flat namespace, or a per-project subdomain.
Routing
Aliases, forwards and catch-all, resolved in a fixed order: explicit mailbox → alias/forward → catch-all → reject.
CI
Scenario engine
Publish an immutable scenario and run it from CI instead of orchestrating the steps in your own test code. Deterministic — no model in the execution path.
Why it doesn't go flaky

Cross-project access returns 404, never 403, so resource existence never leaks. Per-key rate limiting answers with 429 and a Retry-After you can actually back off against. And v1 is additive-only — the integration does not break under you.

UC-3 · AI AGENTS AS CLIENTS

Be the best email tool in the agent's belt

Your coding agent already drives the browser and reads your repo. What it cannot do is receive email. That is the part MailHulk hands over — bounded, labelled, and safe to put in a model's context.

MailHulk performs no inference. Anywhere.

Not to draft a scenario, not to judge an email, not to explain a failure. This is a product boundary, not a phase. The agent in UC-3 is yours — MailHulk ships none of its own, and message content never enters an AI provider on our side. When your agent reads a body, that content enters your provider account under your agreement. There is no consent screen because there is nothing to consent to.

THE MENTAL MODEL

The agent is the automation QA engineer

Today a human explores a flow by hand, then writes a script so CI can run it forever. In UC-3 the agent does the exploring and the writing; the human reviews the artifact.

STEP IN THE QA JOB
HUMAN QA
AI AGENT
WHOSE TOOL
Explore the flow by hand
Clicks through staging
Drives the app
Browser tooling
Get the verification email
Checks a shared Gmail
wait_for_message
MailHulk
Extract the code or link
Copies it by hand
extract
MailHulk
Complete the flow and assert
Writes assertions in test code
Asserts inline while exploring
Mixed
Produce a durable test
Commits a script
Publishes a scenario version
MailHulk
Run it forever in CI
CI runs the script
CI runs the published version — no model in the path
MailHulk
MODE 1
EXPLORATORY
The agent checks a flow

No scenario authored in advance. The agent creates an inbox, drives the app, reads the mail, asserts, reports, and tears down.

1

The MCP server is configured once, with a project-scoped credential in the server's own environment. It is never in a prompt and never appears in a tool result.

2

The agent opens a session. Everything it creates is tagged to that session, and release_session frees all of it in one call.

3

create_inbox declares its side-effect class, so the harness can gate it. Idempotency is automatic — a transport retry cannot leave an orphan inbox.

4

wait_for_message returns {status: "pending", poll_token} at the cap rather than erroring. The agent never blocks a long tool call and never busy-loops.

5

The body arrives truncated to a token budget, with the full length and a part reference for explicit retrieval. A 2 MB marketing email cannot blow the context window.

MODE 2
DURABLE ARTIFACT
The agent leaves a test behind

Where the real leverage is. The agent's most valuable output is not a one-off passing check — it is a published, immutable scenario version.

1

The agent writes the flow it just performed as a schema-typed scenario definition: create inbox → trigger the endpoint → wait for mail → extract the code → verify → assert.

2

It calls validate, which returns structured errors with field paths and codes. The agent fixes and re-validates until clean.

3

It publishes an immutable version. The definition is hashed; the permissions it needs are derived at publish, not asserted by the author.

4

A human reviews the published JSON — a reviewable artifact, exactly as they would review a test PR.

5

CI runs that version from then on, with no agent and no model. Deterministic assertions own pass/fail; evidence is captured on every run.

The agent is now off the critical path. It was the author, not a runtime dependency — the only arrangement under which a model-driven QA workflow is safe to put in CI.

WHY A PLAIN REST API IS NOT ENOUGH

Each row is a way agent integrations actually fail.

AGENT FAILURE MODE
WHAT UC-3 ADDS
A blocking long-poll stalls the agent, or it busy-loops burning tokens
Bounded, resumable wait with a poll token
A 2 MB HTML email consumes the whole context window
Token-bounded responses; explicit full-part fetch
The agent picks a destructive tool because nothing said it was destructive
Declared side-effect class per tool
A crashed agent leaks every resource it created
Session ledger, one-call release, independent session expiry
The API key ends up in the transcript, then a log, then a bug report
Credential read from the server environment — never model-supplied, never echoed
A leaked agent credential has full, permanent project authority
Expiry plus action scopes that can only narrow, never extend
An agent reaches a production project
Per-project environment; agent mutations require a test project
The agent retries the wrong thing because the error was prose
Stable error code, plus retryable and retry_after
A malicious email steers the agent
Untrusted-content envelope with instruction-shaped framing neutralized
Prompt injection — the one that actually matters

An agent reading email is, by construction, feeding attacker-controlled text into a model. Anyone can send mail to a MailHulk address, so a message body is a direct injection channel — and MailHulk is the component that hands it over. So we enforce containment at the serialization boundary: every body, header set and payload is wrapped in an explicit untrusted-content envelope, and instruction-shaped framing is neutralized before it leaves MailHulk. Normal extraction still works — codes[0] is still 123456. This cannot make your agent safe on its own; your harness still has to gate mutations, which is why every tool declares its side-effect class. But MailHulk must not be the component that hands over live ammunition unlabelled.

HOW THEY RELATE

An adoption path, not a funnel

Because the disposable inbox requires an account, it is not acquisition — it is the first useful thing you do after signing up, and the cheapest demonstration that capture works. Doing the task twice by hand suggests automating it the third time.

one pipeline, three front doors
┌──────────────── one mail pipeline ────────────────┐
SMTP → parse → resolveInboxForAddress
MessageWriter::store()MessageReceived
└───────────────────────┬───────────────────────────┘
┌────────────────────────────────┼────────────────────────────────┐
UC-1 dashboard UC-2 /v1 REST UC-3 MCP server
(session auth) (project API key) (scoped agent credential)
human reads mail test suite asserts agent completes a flow
└──── "get this over an API" ────┘
(graduation) └──── thin client of /v1 ────────┘
SHARED — AND MUST STAY SHARED
Ingestion & persistence
One path for every surface. A second one would be a standing violation.
Address resolution
No surface gets its own resolution branch.
Parsed message shape
Link and code extraction is written once; all three benefit.
Long-poll wait
The live list, waitForEmail, and the agent's bounded wait are one mechanism.
Retention & reaping
A disposable inbox is an ephemeral inbox — no second reaper.
ISOLATED — AND MUST STAY ISOLATED
Auth planes
Dashboard sessions and API keys do not mix. The MCP server is a /v1 client, not a third plane.
Tenancy
Every surface is team- and project-scoped. Cross-project reads return 404, never 403.
Agent credentials
Scopes can only reduce project-key authority, never extend it.
MCP server
Thin client — no tenancy logic, no DB access, no privilege /v1 lacks. Anything an agent can do, curl with the same credential can do.
Staff operations
Operational surfaces never appear in the customer namespace or on /v1.
WHERE THINGS STAND

What ships today, and what's next

We publish this because a use-case page that quietly implies everything is finished is a use-case page you can't trust.

CAPABILITY
SURFACE
STATUS
Inboxes, messages, parsing & long-poll
UC-2
AVAILABLE
Webhooks, custom domains, routing, POP3/IMAP
UC-2
AVAILABLE
Deterministic scenario engine — author, validate, publish, run
UC-2
AVAILABLE
HTTP actions so a scenario can trigger your app
UC-2 / UC-3
IN PROGRESS
Disposable addresses in the dashboard
UC-1
IN DESIGN
Agent-ready /v1 — scoped credentials, bounded responses, envelopes
UC-3
IN DESIGN
MCP server
UC-3
IN DESIGN
Anonymous public inboxes, send-side testing, cross-inbox search
NOT PLANNED
Status reflects the product roadmap at the time of publishing. Ask us before you build a launch around a line that isn't marked available.

Pick a door and start

First inbox live in under 60 seconds.

Start free trial