Quickstart

This guide walks you from zero to receiving emails and extracting OTPs via the API. You will create an account, generate an API key, register a disposable inbox, and call the main endpoints.

1. Create an account

Sign up at freecustom.email with Google, GitHub, or email. No credit card required for the Free plan.

2. Go to Dashboard → API tab

After signing in, open your Dashboard and click the API tab. If you do not see it, you are on the main app dashboard; the API tab appears once you have (or can have) an API plan.

3. Generate an API key

In the API dashboard, click Generate new key. Copy the key immediately — it is shown only once. Store it in your environment (e.g. FCE_API_KEY) and never commit it to version control.

4. Register your first inbox

Send a POST /v1/inboxes request with the inbox field (full email address). The address must use a domain we support (e.g. @ditapi.info).

curl -X POST https://api2.freecustom.email/v1/inboxes \
  -H "Authorization: Bearer fce_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"inbox":"mytest@ditapi.info", "isTesting": true}'

Success (201): { "success": true, "data": { "inbox": "mytest@ditapi.info", "registered_at": "2026-03-04T10:00:00.000Z" } }

5. Send a test email

From any email client or script, send an email to the address you registered (e.g. mytest@ditapi.info). For OTP testing, send a message with a subject or body containing a 4–8 digit code.

6. Fetch the inbox messages

Use GET /v1/inboxes/{inbox}/messages to list messages for that inbox.

curl "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/messages" \
  -H "Authorization: Bearer fce_your_api_key"

7. Extract the OTP

On Growth plan and above, GET /v1/inboxes/{inbox}/otp returns the latest detected OTP. On lower plans you receive __DETECTED__ to indicate that an OTP was found — upgrade to Growth to get the actual code.

curl "https://api2.freecustom.email/v1/inboxes/mytest@ditapi.info/otp" \
  -H "Authorization: Bearer fce_your_api_key"

Example response: { "success": true, "data": { "otp": "847291", "score": 0.98, "verification_link": "https://...", "from": "noreply@example.com", "subject": "Your code is 847291", "message_id": "msg_abc", "received_at": "2026-03-04T09:55:00.000Z" } }

8. Subscribe via WebSocket

On Startup plan and above, you can open a WebSocket to receive new messages in real time. See the WebSocket guide for the connection URL and event format.

Setup per language

• Node.js: npm install node-fetch (or use built-in fetch in Node 18+).
• Python: pip install requests.
• Go: use net/http from the standard library.
• PHP: curl extension or Guzzle.

Full API reference

These docs cover every endpoint and feature in the API: authentication, inboxes, messages, OTP extraction, WebSocket, rate limits, credits, and errors. For a machine-readable spec (OpenAPI 3.1), use /openapi.yaml. Try requests in the browser in the Playground.