Code examples

Every example uses GET /v1/inboxes/{address}/code?wait=60. It holds the request open until a verification code or confirmation link arrives, skips mail that has neither, and returns only what you need:

{
  "address": "k3f9xq2m@tikaurasave.site",
  "code": "482913",
  "link": "https://yourapp.com/verify?token=…",
  "messageId": "0b04d44e-…",
  "from": "noreply@yourapp.com",
  "subject": "Confirm your email",
  "receivedAt": "2026-09-25T17:14:20.594Z"
}

If nothing arrives in time it answers 404 with "code": "code_not_found". Set your key as MAILFORNET_API_KEY first.

cURL

KEY="Authorization: Bearer $MAILFORNET_API_KEY"

ADDRESS=$(curl -s -X POST https://api.mailfornet.com/v1/inboxes -H "$KEY" \
  -H "Content-Type: application/json" -d '{"ttlMinutes": 30}' | jq -r .address)

# … sign up with $ADDRESS …

curl -s "https://api.mailfornet.com/v1/inboxes/$ADDRESS/code?wait=60" -H "$KEY" | jq -r .code

Node.js (fetch, no dependencies)

const API = 'https://api.mailfornet.com/v1';
const headers = { Authorization: `Bearer ${process.env.MAILFORNET_API_KEY}`, 'Content-Type': 'application/json' };

const { address } = await fetch(`${API}/inboxes`, { method: 'POST', headers, body: '{}' }).then((r) => r.json());

await signUp(address);

const res = await fetch(`${API}/inboxes/${encodeURIComponent(address)}/code?wait=60&subject=verify`, { headers });
if (!res.ok) throw new Error(`No code: ${(await res.json()).error.code}`);
const { code, link } = await res.json();

Node.js (npm client)

npm install mailfornet

import Mailfornet from 'mailfornet';

const mf = new Mailfornet(); // reads MAILFORNET_API_KEY
const inbox = await mf.createInbox({ ttlMinutes: 30 });

await signUp(inbox.address);

const code = await mf.waitForCode(inbox.address, { subject: 'verify', timeout: 60 });

Python

import os, requests

API = "https://api.mailfornet.com/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['MAILFORNET_API_KEY']}"

address = s.post(f"{API}/inboxes", json={"ttlMinutes": 30}).json()["address"]

sign_up(address)

r = s.get(f"{API}/inboxes/{address}/code", params={"wait": 60, "subject": "verify"}, timeout=70)
r.raise_for_status()
code = r.json()["code"]

PHP

$api = 'https://api.mailfornet.com/v1';
$auth = 'Authorization: Bearer ' . getenv('MAILFORNET_API_KEY');

$ch = curl_init("$api/inboxes");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_POSTFIELDS => '{}', CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [$auth, 'Content-Type: application/json']]);
$address = json_decode(curl_exec($ch), true)['address'];

sign_up($address);

$ch = curl_init("$api/inboxes/" . urlencode($address) . "/code?wait=60");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 70, CURLOPT_HTTPHEADER => [$auth]]);
$code = json_decode(curl_exec($ch), true)['code'];

Go

func verificationCode(address string) (string, error) {
	req, _ := http.NewRequest("GET", "https://api.mailfornet.com/v1/inboxes/"+url.PathEscape(address)+"/code?wait=60", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("MAILFORNET_API_KEY"))
	res, err := (&http.Client{Timeout: 70 * time.Second}).Do(req)
	if err != nil {
		return "", err
	}
	defer res.Body.Close()
	if res.StatusCode != 200 {
		return "", fmt.Errorf("no code, status %d", res.StatusCode)
	}
	var out struct{ Code string `json:"code"` }
	return out.Code, json.NewDecoder(res.Body).Decode(&out)
}

Tips

• Set your HTTP timeout above the wait. A 60-second wait needs a client timeout of about 70 seconds.
• Filter when your app sends several mails. from and subject match on a substring.
• Need the whole email? GET /v1/messages/{messageId}?address=… returns text, HTML, every link and the code.
• Retrying creates? Send an Idempotency-Key header and a retried request returns the same inbox.

Framework guides

Playwright · Cypress · Selenium & Python · AI agents (MCP)