Guide 1 of 8
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
Sign up at app.mailfork.dev — takes about 30 seconds.
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.
- 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.
Create a Team
A team groups inboxes together. It maps to the subdomain between the inbox name and your org.
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({
orgSlug: 'acme',
slug: 'qa',
});
console.log(team.id);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.
Via web UI: Team page → Inboxes → New Inbox → enter a username → Create.
Via SDK / API:
const inbox = await mf.inboxes.create({
teamSlug: 'qa',
orgSlug: 'acme',
username: 'ci',
});
console.log(inbox.address); // [email protected]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:manage.
- 4. Click Create and copy the key immediately — it is only shown once.
MF_API_KEY.
Install the SDK
The TypeScript/JavaScript SDK handles polling, OTP extraction, and alias lifecycle for you.
npm install @mailfork/sdk
# or
pnpm add @mailfork/sdk
Send a Test Email
Use nodemailer or any SMTP client to deliver an email to your inbox over real SMTP.
import nodemailer from 'nodemailer';
const transporter = nodemailer.createTransport({
host: 'mail.mailfork.dev',
port: 25,
// Haraka uses a self-signed cert — required in test environments
tls: { rejectUnauthorized: false },
});
await transporter.sendMail({
from: '[email protected]',
to: '[email protected]',
subject: 'Your verification code',
text: 'Your OTP is 482910. It expires in 5 minutes.',
});rejectUnauthorized: false? Haraka offers STARTTLS with a self-signed certificate. This flag tells nodemailer to accept it. Safe in test environments — production senders use trusted certs.
Read the Email via SDK
List emails in your inbox — 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 result = await mf.emails.list({
inbox: '[email protected]',
limit: 1,
});
console.log(result.items[0].subject);
console.log(result.items[0].bodyPreview);Extract an OTP
One call. The SDK polls until the email arrives, then returns the extracted code.
const result = await mf.emails.extractOtp({
inbox: '[email protected]',
waitTimeoutMs: 15000, // wait up to 15s for the email to arrive
receivedAfter: new Date(Date.now() - 5 * 60 * 1000), // last 5 minutes only
});
console.log(result.otp); // "482910"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.