Getting Started

By the end of this guide you'll have an org, team, and inbox set up — and you'll have sent a test email and extracted an OTP code from it, all via the SDK.

Org, team, and inbox created
API key generated
Test email sent and received
OTP extracted with a single SDK call

Create Your Account

Google OAuth

Click "Continue with Google", authorize, and you're in. No password required.

Magic Link

Enter your email address. A login link is sent to your inbox — expires in 15 minutes, single-use.

Create an Org

An org is your top-level namespace. Every email address you create will live under it.

ci@qa.acme.mailfork.dev ← your org slug

1. After login, click Create Organization.
2. Enter a slug (e.g., acme). This becomes part of every email address in your org. It must be globally unique.
3. Click Create.

Note: Org creation is only available through the web UI during onboarding. You'll be prompted right after your first login.

Create a Team

A team groups inboxes together. It maps to the subdomain between the inbox name and your org.

ci@qa.acme.mailfork.dev ← team slug

Via web UI: Open your org → Teams → New Team → enter a slug (e.g., qa) → Create Team.

Via SDK / API:

import { MailForkClient } from '@mailfork/sdk';

const mf = new MailForkClient({ apiKey: process.env.MF_API_KEY });

const team = await mf.teams.create('qa', 'QA Team');
console.log(team.id);

const { MailForkClient } = require('@mailfork/sdk');

const mf = new MailForkClient({ apiKey: process.env.MF_API_KEY });

const team = await mf.teams.create('qa', 'QA Team');
console.log(team.id);

curl -X POST https://api.mailfork.dev/v1/teams \
  -H "X-API-Key: $MF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "slug": "qa", "display_name": "QA Team" }'

Create an Inbox

An inbox is a named email destination within a team. You can have multiple inboxes per team — one per test suite, feature area, or workflow.

ci@qa.acme.mailfork.dev ← inbox username

Via web UI: Team page → Inboxes → New Inbox → enter a username → Create.

Each inbox has a UUID used in all SDK calls. Find it in the web UI under the inbox name, or look it up with the SDK:

// List your inboxes to find the inbox UUID
const inboxes = await mf.inboxes.list();
const inbox = inboxes.find(i => i.username === 'ci');

console.log(inbox.id);       // UUID used in all SDK calls
console.log(inbox.username); // ci

const inboxes = await mf.inboxes.list();
const inbox = inboxes.find(i => i.username === 'ci');

console.log(inbox.id);       // UUID used in all SDK calls
console.log(inbox.username); // ci

curl https://api.mailfork.dev/v1/inboxes \
  -H "X-API-Key: $MF_API_KEY"

Create Your First API Key

You need an API key to use the SDK and REST API.

1. Go to Settings → API Keys → New API Key.
2. Give it a name, e.g. local-dev.
3. Select scopes: check emails:read and inboxes:read.
4. Click Create and copy the key immediately — it is only shown once.

Never commit your API key to source control. Store it as an environment variable: MF_API_KEY.

Install the SDK

The TypeScript/JavaScript SDK handles polling, OTP extraction, and alias lifecycle for you.

bash

npm install @mailfork/sdk
# or
pnpm add @mailfork/sdk

Read the Email via SDK

List emails in your inbox using its UUID — the SDK returns the subject, sender, and a preview of the body.

import { MailForkClient } from '@mailfork/sdk';

const mf = new MailForkClient({ apiKey: process.env.MF_API_KEY });

const INBOX_ID = 'your-inbox-uuid'; // copy from the web UI

const emails = await mf.emails.list(INBOX_ID, { limit: 1 });

console.log(emails[0].subject);
console.log(emails[0].body_preview);

const { MailForkClient } = require('@mailfork/sdk');

const mf = new MailForkClient({ apiKey: process.env.MF_API_KEY });

const INBOX_ID = 'your-inbox-uuid';

const emails = await mf.emails.list(INBOX_ID, { limit: 1 });

console.log(emails[0].subject);

curl "https://api.mailfork.dev/v1/inboxes/{inboxId}/emails?limit=1" \
  -H "X-API-Key: $MF_API_KEY"

Extract an OTP

One call. The SDK polls until the email arrives, then returns the extracted code.

const otp = await mf.emails.extractOtp(INBOX_ID, {
  wait_timeout_ms: 15_000, // wait up to 15s for the email to arrive
});

console.log(otp); // "482910"

const otp = await mf.emails.extractOtp(INBOX_ID, {
  wait_timeout_ms: 15_000,
});

console.log(otp); // "482910"

curl "https://api.mailfork.dev/v1/inboxes/{inboxId}/emails/extract-otp?wait_timeout_ms=15000" \
  -H "X-API-Key: $MF_API_KEY"

Auto-detect mode: When no pattern is provided, MailFork uses a ranked library of common OTP patterns (6-digit codes, "Your code is X", "verification code: X", etc.) and returns the highest-confidence match. Using a non-standard format? See OTP Extraction →

You're set up. 🎉

You've sent a real email to a real inbox and extracted an OTP from it. Everything from here is about making this workflow faster and more robust in your test suite.

What's next?

Working with Aliases →

Isolate each test run with an ephemeral alias that auto-expires.

OTP Extraction →

Custom regex patterns and advanced polling options.

CI/CD Integration →

GitHub Actions setup with per-test aliases and zero cleanup.