FreeCustom.Email API
Last updated: May 2026 Disposable email infrastructure for developers. All routes require Authorization: Bearer fce_ (developer API key), except GET /v1/plans…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Last updated: May 2026
Disposable email infrastructure for developers.
All routes require Authorization: Bearer fce_ (developer API key), except GET /v1/plans and GET /v1/otp/public which are public.
IMAP & POP3 (Growth/Enterprise)
In addition to the HTTP API, Growth and Enterprise plans can read inboxes via standard mail protocols (TLS only):
| Protocol | Host | Port | Auth |
|---|---|---|---|
| IMAP4rev1 | imap.freecustom.email | 993 | username = inbox address, password = fce_ key |
| POP3 | pop.freecustom.email | 995 | username = inbox address, password = fce_ key |
Connecting and listing messages are free. Fetching a message body (IMAP FETCH / POP3 RETR) costs 1 request from the monthly quota. Docs: https://freecustom.email/api/docs/imap
Endpoints 25
Public v1 - Account
- GETGet current user (account info)
/v1/meReturns the authenticated developer's account info — plan, rate limits, feature flags, inbox count, credit balance, and custom domain count. - GETGet usage stats
/v1/usageReturns live usage stats for the current billing period. - GETList plans and credit packages
/v1/plansPublic endpoint — no auth required. Returns all available plans and credit packages.
Public v1 - Platform Domains
- GETList available platform domains
/v1/domainsReturns the platform-managed domains available for inbox creation, filtered by your plan: Free / Developer / Startup — free-tier domains only. Growth /… - GETList all platform domains with full metadata
/v1/domains/allSame domain list as GET /v1/domains but always includes full expiry metadata for every domain — useful for dashboard integrations that monitor domain health…
Public v1 - Custom Domains
- GETList your custom domains
/v1/custom-domainsReturns all custom domains you have added to your account, along with their verification status and the DNS records needed to verify them. Plan required:… - POSTAdd a custom domain
/v1/custom-domainsAdds a new custom domain to your account and returns the DNS records you must configure at your registrar before verifying. Plan required: Growth ($89/mo) or… - DELETERemove a custom domain
/v1/custom-domains/:domainPermanently removes a custom domain from your account. Side effects: All API inboxes registered at @{domain} are automatically unregistered. The domain is… - POSTVerify a custom domain
/v1/custom-domains/:domain/verifyTriggers a live DNS check for the domain's MX and TXT records. Call this after you have added the two records at your registrar. DNS records required: The…
Public v1 - Inboxes
- GETList inboxes
/v1/inboxes - POSTRegister an inbox
/v1/inboxesRegisters an inbox for API use. Platform domain inbox: The domain must appear in GET /v1/domains for your plan. Custom domain inbox: The domain must be added… - DELETEUnregister an inbox
/v1/inboxes/:inbox - POSTStart a new test run
/v1/inboxes/:inbox/testsMarks the start of a testing boundary for this inbox. Useful in test suites (Playwright, Cypress, Selenium) to group timeline events together under a single… - POSTBulk-generate inboxes (Inbox Generator)
/v1/inboxes/generateBulk-creates random disposable inboxes and registers them to your account in one call. Each inbox comes with a long-lived per-inbox OTP token URL that lets…
Public v1 - Messages
- GETList messages
/v1/inboxes/:inbox/messagesReturns the summary of every message in the inbox (up to the 200 most recent), newest first, in a single response. There are no pagination parameters. Use GET… - GETGet a message
/v1/inboxes/:inbox/messages/:id - DELETEDelete a message
/v1/inboxes/:inbox/messages/:id - GETWait for next message (Long Polling)
/v1/inboxes/:inbox/waitWait for a new email to arrive in the specified mailbox (Long Polling). This eliminates the need for rapid polling and reduces request overhead. Plan…
Public v1 - OTP
- GETPoll OTP via public token (no API key needed)
/v1/otp/public?token=fceotp_24f1add500d18150a02c62e40b395828226a79abReturns the latest OTP for an inbox using a long-lived per-inbox token generated by POST /v1/inboxes/generate. No API key is required — safe to embed in… - GETGet latest OTP
/v1/inboxes/:inbox/otpReturns the OTP and/or verification link from the most recent message that contains one. Requires Startup plan or higher. Cost: 3 requests. On lower plans,…
Public v1 - Webhooks
- GETList active webhooks
/v1/webhooksList all active webhook subscriptions for your account. Plan Requirement: Growth or above. - POSTRegister a webhook
/v1/webhooksSubscribe to real-time message notifications via webhook. Plan Requirement: Growth or above. Cost per Webhook Delivery: Basic (No OTP): 2 requests OTP Present… - DELETEUnregister a webhook
/v1/webhooks/:idDelete an existing webhook subscription by ID. Plan Requirement: Growth or above.
Public v1 - Dashboard Analytics
- GETGet inbox timeline history
/v1/inboxes/:inbox/timelineReturns the timeline history for a specific inbox. This shows the test run history and event sequence for debugging failed tests. Plan required: Growth… - GETGet inbox failure insights
/v1/inboxes/:inbox/insightsReturns automated failure insights for a specific inbox. This analyzes the inbox activity and detects common issues with test flows. Plan required: Growth…
API details
- Base URL
https://api2.freecustom.email- Authentication
- A bearer token in the Authorization header
An API key in the api_key query parameter - Operations
- 25 operations on 21 pathsGET 15POST 6DELETE 4
- Main resources
- Public v1 - Inboxes 5Public v1 - Custom Domains 4Public v1 - Messages 4Public v1 - Account 3Public v1 - Webhooks 3Public v1 - Dashboard Analytics 2Public v1 - OTP 2Public v1 - Platform Domains 2
- Response formats
application/json- Description format
- OpenAPI 3.1.0, API version
2.2.0 - Links
- OpenAPI document
- Listed from
- Freecustom's published OpenAPI description
How to test the FreeCustom.Email API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the FreeCustom.Email API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Get current user (account info)” (GET /v1/me), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the FreeCustom.Email API?
Last updated: May 2026 Disposable email infrastructure for developers. All routes require Authorization: Bearer fce_ (developer API key), except GET /v1/plans… It is listed under Communication and has 25 endpoints.
Who publishes the FreeCustom.Email API?
It is listed from Freecustom's public API description (an OpenAPI document), not published by Freecustom on Swastik Codes. Anyone who controls freecustom.email can claim the profile by adding a DNS TXT record.
What is the base URL of the FreeCustom.Email API?
Requests go to https://api2.freecustom.email. Endpoint paths are added to this base URL.
How do I authenticate with the FreeCustom.Email API?
It accepts 2 methods: A bearer token in the Authorization header; an API key in the api_key query parameter.
How many endpoints does the FreeCustom.Email API have?
25 operations on 21 paths (15 GET, 6 POST, 4 DELETE). The largest groups are Public v1 - Inboxes, Public v1 - Custom Domains, Public v1 - Messages, Public v1 - Account.
Is forking the FreeCustom.Email API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.