Quickstart

Sign in with your email#

Open the sign in page and enter your email. We send you a link and a 6 digit code; click the link or type the code. Both work once and for 15 minutes. There is no password.

The first time you sign in we create your account and a workspace. Each workspace gets a private, random code and with it its own domain, such as k7m3qz.mailbay.email. Nothing else is made until you choose what to set up first: add your own domain, or just try it, which makes your Playground. Any address under your code, for example hello@k7m3qz.mailbay.email, receives mail right away and lands in the Playground's Catch-all inbox: send it a message from any account and watch it arrive in the dashboard.

Create an API key#

Apps, agents and the CLI use API keys. In the dashboard, open API keys and choose Create key. Keys start with mb_live_, are shown once, and can be limited to one inbox. Send the key as a bearer token.

curl https://api.mailbay.dev/v1/inboxes \
  -H "Authorization: Bearer $MAILBAY_API_KEY"

Create an inbox#

Pick the part before the @. The inbox lives on your workspace's code domain and receives mail as soon as the request returns. Without a named inbox, the same address still reaches your Catch-all.

curl -X POST https://api.mailbay.dev/v1/inboxes \
  -H "Authorization: Bearer $MAILBAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"local_part": "support"}'

{
  "id": "ibx_01jbz8w4k2q9...",
  "org_id": "org_01jbz7t0a1b2...",
  "address": "support@k7m3qz.mailbay.email",
  "local_part": "support",
  "domain": "k7m3qz.mailbay.email",
  "display_name": "Support",
  "created_at": "2026-10-13T09:40:52Z"
}

Receive an email#

Send a message to the new address from any mail account, then wait for it. The wait endpoint holds the request open until a matching message arrives and returns any codes and links it finds.

curl "https://api.mailbay.dev/v1/inboxes/ibx_01jbz8w4k2q9/wait?timeout=60" \
  -H "Authorization: Bearer $MAILBAY_API_KEY"

# On the Catch-all, wait for one made up address:
curl "https://api.mailbay.dev/v1/inboxes/ibx_catchall/wait?to=signup-42@k7m3qz.mailbay.email&timeout=60" \
  -H "Authorization: Bearer $MAILBAY_API_KEY"

Use the CLI#

The mailbay CLI is a single Rust binary. It is not on a package registry yet; build it from a checkout of the Mailbay repository, then sign it in with an API key.

cargo install --path crates/cli

mailbay login            # paste your API key, it is checked and saved
mailbay inbox create support
mailbay inbox list
mailbay wait ibx_01jbz8w4k2q9 --timeout 2m

It also has whoami, messages, message, threads and thread. Add --json to any command for the raw API answer.

Next: Inboxes, Messages and threads, or put the inbox on your own domain with Domains.