inboxkit

Bulk disposable inboxes for testing your own signup, verification, and onboarding flows.

Five backends, same API. Switch with INBOXKIT_PROVIDER.

Free, nothing to sign up for:

• mailtm: real throwaway inboxes on Mail.tm's shared domains. No key, no domain of your own, and the app can read the mail, so verification codes come straight back out.
• mailgw: the same API run by a different operator (mail.gw). Useful as a fallback when Mail.tm is rate-limiting or down.
• guerrilla: Guerrilla Mail's public JSON API. Readable immediately, but the addresses are public and messages are dropped after about an hour.

Yours, or paid:

• local (default): generates N unique addresses on a domain you control, either catch-all (checkout-a1b2c3d4@yourdomain.com) or plus-addressed (you+checkout-a1b2c3d4@gmail.com). Mail lands in a mailbox you already own. The durable option, since nothing can disappear out from under you.
• mailslurp: real, readable inboxes over MailSlurp's documented API. Needs MAILSLURP_API_KEY.

The three free providers create a live account or session per address, so a bulk run is paced to stay inside their rate limits: expect roughly two or three inboxes a second rather than the instant return you get from local. Their inboxes also live in the running process, so a restart loses the handles (the local provider is pure string work and has no such limit).

Run

pip install -r requirements.txt
export INBOXKIT_PROVIDER=local
export INBOXKIT_DOMAIN=yourdomain.com      # a domain you actually control
export INBOXKIT_MODE=catchall              # or: plus, with INBOXKIT_BASE=you
uvicorn app.main:app --reload

Open http://127.0.0.1:8000 for the UI, or http://127.0.0.1:8000/docs for the API.

For free readable inboxes with no domain and no key:

export INBOXKIT_PROVIDER=mailtm      # or: mailgw, guerrilla

For MailSlurp:

export INBOXKIT_PROVIDER=mailslurp
export MAILSLURP_API_KEY=sk_...

API

Method	Path	Does
POST	/inboxes/bulk	{"count": 50, "tag": "checkout"} -> 50 addresses
GET	/inboxes	list everything created
GET	/inboxes.csv	same, as CSV for your test fixtures
GET	/inboxes/{id}/messages	messages, each with a parsed code and links
GET	/inboxes/{id}/code?timeout=60	poll until the verification code lands
DELETE	/inboxes/{id} / /inboxes	teardown one or all

Example: end-to-end signup test

import httpx
kit = "http://127.0.0.1:8000"
box = httpx.post(f"{kit}/inboxes/bulk", json={"count": 1, "tag": "e2e"}).json()["inboxes"][0]

httpx.post("https://yourapp.test/signup", json={"email": box["address"]})
code = httpx.get(f"{kit}/inboxes/{box['id']}/code", params={"timeout": 60}).json()["code"]
httpx.post("https://yourapp.test/verify", json={"email": box["address"], "code": code})

httpx.delete(f"{kit}/inboxes/{box['id']}")

Notes

INBOXKIT_MAX_BULK (default 200) caps a single bulk call. INBOXKIT_MAILTM_PACE and INBOXKIT_GUERRILLA_PACE (seconds between calls) tune the pacing on the free providers if you start seeing 429s. This is built for exercising services you own or have permission to test, not for creating accounts on someone else's.

Tests

pytest -q