Skip to content

Quickstart

By the end of this page you will have:

  1. Received a real email at an @mailfade.dev address you made up;
  2. Read it back over HTTP from your terminal;
  3. Done the same thing from Python and from a Playwright test.

No signup is needed for any of this. Get a Dev key only once you want longer retention, attachments, or higher rate limits.

1. Pick an address and send mail to it

Pick any local-part. Whatever you put before the @ becomes an inbox the instant the first mail arrives.

echo "Hello from your laptop" | mail -s "Test" [email protected]

If you don’t have mail installed, send from Gmail, Fastmail, or anywhere — just hit Send to [email protected].

2. Read it back

curl https://api.mailfade.dev/inbox/[email protected]

You should see something like:

{
  "address": "[email protected]",
  "count": 1,
  "emails": [
    {
      "id": "01HF5K9X2E4...",
      "sender": "[email protected]",
      "subject": "Test",
      "has_attachments": false,
      "received_at": 1716729384213,
      "expires_at": 1716732984213
    }
  ]
}

Fetch the body:

curl https://api.mailfade.dev/message/01HF5K9X2E4...

That’s the whole API surface for reading. You will spend more time wiring it into your test framework than learning it.

3. Wire it into a real test

Python

import os, time, requests

API = "https://api.mailfade.dev"
KEY = os.environ.get("MAILFADE_KEY")  # optional on free tier
HEADERS = {"Authorization": f"Bearer {KEY}"} if KEY else {}

def wait_for_email(inbox, timeout=30):
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{API}/inbox/{inbox}", headers=HEADERS).json()
        if r["count"]:
            return r["emails"][0]
        time.sleep(1)
    raise AssertionError(f"No email in {inbox} after {timeout}s")

Playwright (TypeScript)

import { test, expect, request as pwRequest } from "@playwright/test";

test("signup verification email arrives", async ({ page }) => {
  const inbox = `pw-${Date.now()}@mailfade.dev`;
  const api = await pwRequest.newContext({
    baseURL: "https://api.mailfade.dev",
    extraHTTPHeaders: process.env.MAILFADE_KEY
      ? { Authorization: `Bearer ${process.env.MAILFADE_KEY}` }
      : {},
  });

  await page.goto("/signup");
  await page.getByLabel("Email").fill(inbox);
  await page.getByRole("button", { name: "Sign up" }).click();

  await expect.poll(async () => {
    const r = await api.get(`/inbox/${inbox}`);
    return (await r.json()).count;
  }, { timeout: 30_000 }).toBeGreaterThan(0);
});

4. (Optional) Get a Dev key

If you want more than 100 req/day, longer retention, attachments, or HTML body access on the API, grab a Dev key — $19/mo by card, or 20,000 sats over Lightning. The key is returned once at checkout; store it in your CI secrets and send it as Authorization: Bearer <key>.

Next