Skip to main content

Create an Inbox

Set up a test inbox, send mail to it, and read what arrives.

From the dashboard​

  1. Open Email in the sidebar
  2. Click New inbox
  3. Enter a name (for example "Signup tests") and, optionally, a slug
  4. Click Create. The inbox page shows its receiving address:
[email protected]

You can also create inboxes with the REST API (POST /api/v1/inboxes) or let an AI agent call create_inbox through the MCP server. To get an address with no account at all, see Inboxes without an account.

Email address format​

<slug>@hookinbox.com

The slug is generated from the inbox name unless you choose one: lowercase letters, numbers and hyphens, unique across Hooklistener. It is the inbox's address, so it can't change after creation; create a new inbox for a new address.

Plus-addresses land in the same inbox: mail to <slug>[email protected] is captured too. Give every test run its own plus-address and filter on it with to so runs never read each other's mail.

Sending emails to it​

The address is a real mailbox on the internet. Mail sent from anywhere is captured:

  • Your application, through its usual email provider (SendGrid, Postmark, SES, Resend…)
  • A staging environment's signup, login or password-reset flow
  • Your own mail client, for a quick check

Store a message over HTTP​

Test harnesses can also put a message straight into an inbox with the API, without sending real mail. The message is stored, counted and forwarded like received mail, and waits wake up for it:

curl -X POST https://app.hooklistener.com/api/v1/inboxes/INBOX_ID/messages \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your verification code",
    "text": "Your verification code is 482913."
  }'

Send a raw MIME message with Content-Type: message/rfc822 instead to include attachments. See Store a message.

Reading captured emails​

Emails appear on the inbox page in real time, newest first. Open one to see:

  • From, to, subject and date
  • HTML body, rendered, and the plain-text body
  • Headers, in order
  • Attachments and inline images, each with a download button

From code, the same email comes with the one-time code and confirmation link extracted.

Managing an inbox​

The inbox page has three actions:

ActionWhat it does
RenameChanges the display name. The address stays the same
ClearDeletes every email but keeps the inbox and its address. On Free, the 10-email allowance frees up at once
DeleteDeletes the inbox and every email in it. Mail to its address is no longer received, and the inbox stops counting toward your plan's limit

You can also delete a single email from its page. The same actions are available through the REST API and the MCP tools delete_emails and delete_inbox.

Below the address, Forwarding lets you POST every received email to a webhook. See Forward email to webhooks.

Limits​

  • Free: 1 inbox, up to 10 emails per inbox in any rolling 24 hours. Mail over the limit is rejected until older emails leave the window or you clear the inbox.
  • Pro: 5 inboxes. Production and Scale: unlimited inboxes. Paid plans accept unlimited emails per inbox.
  • Retention: emails are deleted automatically once they are older than your plan's request history (Free 1 day, Pro 14, Production 30, Scale 90 days). Attachments are kept with their email.

Next steps​