Recipes

Playwright E2E test with a fresh inbox

import { test, expect } from '@playwright/test';

const API = 'https://app.squadmail.dev/api/v1';
const auth = { authorization: `Bearer ${process.env.SQUADMAIL_KEY}` };

test('sign-up sends a verification code', async ({ page, request }) => {
	const inbox = await (
		await request.post(`${API}/inboxes`, {
			headers: auth,
			data: { ttl_minutes: 15, agent_name: 'e2e', tags: ['signup'] }
		})
	).json();

	await page.goto('https://staging.example.com/signup');
	await page.fill('#email', inbox.address);
	await page.click('text=Create account');

	const res = await request.get(`${API}/inboxes/${inbox.id}/wait?timeout=60&subject=verify`, {
		headers: auth
	});
	const mail = await res.json();
	await page.fill('#code', mail.extracted.code);
	await expect(page.getByText('Welcome')).toBeVisible();
});

wait returns mail that arrived after the call started by default. Pass since with the time you triggered the email if it may arrive before you start waiting.

GitHub Actions

- name: E2E
  env:
    SQUADMAIL_KEY: ${{ secrets.SQUADMAIL_KEY }}
  run: pnpm playwright test

Use a key of type ci with read, write scopes. Disposable inboxes clean up after themselves.

Support triage with labels and webhooks

1. Create a permanent inbox support@example.com.
2. Add labels such as billing (“Is this about invoices, refunds or payments?”) and urgent (“Is the customer blocked or reporting an outage?”).
3. Create a webhook for email.labeled filtered to urgent that posts into your on-call tool.

One inbox per agent

Give each long-running agent its own permanent inbox and name: research@acme-agents.com, billing-bot@…. The Overview page shows activity per agent; API keys per agent let you revoke one without touching the others.

Catch-all for multi-tenant tests

Enable catch-all on a dedicated test domain such as acme-tests.com. Every test can use run-UUID@acme-tests.com without creating the inbox first — it appears on first mail.