Test Emails with AI Agents

A coding agent can't receive email on its own. Connected to Hooklistener, Claude Code, Codex, Cursor or any other MCP client can create an inbox, sign up in your app with its address, wait for the email, and finish the flow with the code or link it contains.

Connect the agent

• With an account: connect the MCP server. The quickest way is Connect with one prompt; see Setup for each client. create_inbox is always listed. The rest of the email tools are listed once your organization has an inbox: reconnect the client after the first one (for example /mcp in Claude Code), or send x-hooklistener-toolsets: email.
• Without an account: the agent can follow https://app.hooklistener.com/llms.txt and create an inbox without an account with curl. It lasts an hour by default and needs no token to create.

Ask for it

"Sign up on http://localhost:3000/signup with a Hooklistener inbox and finish the signup with the code from the email."

"Sign up a test user with a Hooklistener inbox address, request a password reset for it, and check that the link in the email opens the reset form."

"Invite a Hooklistener inbox address as a teammate from the settings page and check the invitation email: subject, sender and the accept link."

"Check that the order confirmation email has the PDF invoice attached."

What the agent does

1. Gets an inbox. It calls list_inboxes to reuse one, or create_inbox. The reply has the email_address and email_retention (how long emails are kept and how many the inbox accepts).
2. Starts waiting first. It calls wait_for_email with the inbox_id and to set to a unique plus-address, such as [email protected]. By default the tool returns a task receipt at once, so the agent can trigger the email and then read the result from hooklistener://tasks/{task_id}. If it already triggered the email, it passes since (a timestamp from before) and gets an email that already arrived at once.
3. Triggers the email. It signs up, logs in or resets a password with that plus-address, in a browser tool, with curl, or by running your test.
4. Finishes the flow. The email includes code (the likely one-time code) and verification_link (the likely confirm, magic sign-in, reset or invite link), plus all codes and links. To read the email itself, it calls get_email with include_text: true and gets text, a readable plain-text version.
5. Cleans up if you ask: delete_emails for one email or the whole inbox, delete_inbox for the inbox.

Plus-addresses and to keep the agent's mail apart from your CI runs and from other agents using the same inbox.

Email tools

Tool	What it does	Main parameters
create_inbox	Create an inbox	name, optional slug
list_inboxes	List inboxes with their addresses, email counts and webhook forwards	—
wait_for_email	Wait for the next matching email	inbox_id, to, since, from, subject_contains, timeout (max 60 s), blocking, include_text
list_emails	List emails, newest first	inbox_id, to, since, from, subject_contains, page, page_size
get_email	Get one email with code, verification_link, codes, links and attachments	inbox_id, email_id, include_text, include_body, include_raw_headers, include_raw
delete_emails	Delete one email (email_id), or every email in the inbox	inbox_id, email_id, dry_run, confirmed
delete_inbox	Delete an inbox and its emails	inbox_id, dry_run, confirmed
set_inbox_forward	Create or update a webhook forward	inbox_id, url, forward_id, enabled, to, from, subject_contains
delete_inbox_forward	Delete a webhook forward	inbox_id, forward_id, dry_run, confirmed

The delete tools change nothing until called with confirmed: true; dry_run: true shows what would be deleted. See Available Tools for the full list.

Attachments

get_email and wait_for_email list each attachment and inline image with its index, filename, content_type and size_bytes. The agent reads one through the MCP resource:

hooklistener://email/messages/{email_id}/attachments/{index}

Text attachments come back as text, others as base64. Attachments over 1 MiB are refused; download them from the attachment's download_url with an API key instead.

Tell the agent once

Add a short section to your project's AGENTS.md or CLAUDE.md so every session tests emails the same way:

## Hooklistener
- To test signup, login and reset emails, use the Hooklistener inbox "Signup tests"
  ([email protected]). Sign up with a plus-address such as
  signup-tests+<task>@hookinbox.com, start wait_for_email with `to` set to it
  before triggering the email, then use `code` or `verification_link`.

Add how your local app sends real email, if it needs a setting for that.

Things to know

• The app has to send real mail. Development setups that keep mail on the machine (a local mail catcher, a log-only adapter) never deliver to @hookinbox.com. Point the app at a real provider, or have the agent store a test message with POST /api/v1/inboxes/:id/messages.
• Free plan: one inbox and 10 emails per inbox in any rolling 24 hours. When an inbox is full, delete_emails frees the allowance at once.
• Read-only access lets the agent read inboxes and emails, but not create inboxes or delete anything.