FreeCustom.Email Inbox Generator: Bulk Inboxes with Pre-Signed OTP URLs Explained

What Is the Inbox Generator?

The FreeCustom.Email Inbox Generator is a specialized API endpoint that generates randomized email inboxes in bulk — each one bundled with a pre-signed OTP fetch URL your bot can poll directly. It's available to Developer plan users and above.

Unlike standard inbox creation (where you provision an inbox and then separately query it with your API key), the Generator returns everything your script needs in one response: the email address, a per-inbox token, and a ready-to-use OTP URL that works without any credentials at poll time.

This is the key design insight: by embedding authentication into the URL at generation time, you decouple the generation step (which requires your key) from the polling step (which your bot threads can do freely, in parallel, without credential management).

The OTP URL: What It Is and Why It Matters

Every inbox returned by the generator includes an otp_url field. Here's what a typical one looks like:

https://api2.freecustom.email/v1/otp/public?token=fceotp_24f1add500d18150a02c62e40b395828226a79ab&since=1716900000000&parseCode=true

Breaking it down:

• token=fceotp_... — per-inbox authentication token, valid for days up to 365 depending on plan
• since=1716900000000 — Unix millisecond timestamp from generation time; only returns emails after this moment
• parseCode=true — instructs the server to extract the OTP from the email body automatically

Your bot hits this URL with a plain GET request — no Authorization header, no API key. The server returns the OTP if an email has arrived, or null if not. That's it.

The URL Parameters That Power Your Bot

?since= — Timestamp Anchoring

The since= parameter is one of the most important features for automation correctness. It ensures your bot only sees emails that arrived after the inbox was generated — preventing false positives from old emails or replayed verification codes.

When the generator runs with genSinceNow=true (the default in the UI), it automatically embeds the current Unix timestamp in milliseconds into every OTP URL. Your bot never has to manage this manually.

?parseCode=true — Auto OTP Extraction

Without parseCode=true, the endpoint returns raw email metadata. With it, the server parses the email body and subject to extract 4–8 digit numeric codes automatically, returning them in the otp field of the response.

This means your bot doesn't need to write regex, handle HTML email parsing, or deal with different verification email formats. The extraction is handled server-side.

?wait=N — Long-Polling (Growth/Enterprise)

On Growth and Enterprise plans, you can append wait=N to the OTP URL (or have the generator embed it at generation time). When your bot hits the URL with wait=15 (for example), the request blocks for up to 15 seconds waiting for an email to arrive.

This eliminates polling loops entirely. Instead of hitting the endpoint every 3 seconds, you make one request that returns the moment the email arrives — or times out after N seconds with otp: null.

Enterprise plans support up to 120 seconds of wait time. Growth plans support up to 15 seconds.

Username Styles and Domain Control

8 Username Styles

The generator supports 8 different username styles to match real-world name patterns or generate truly random strings:

• Firstname.Surname — alice.smith@... (with configurable separator)
• Firstnamelastname — alicesmith@...
• Firstnamelastname+digits — alicesmith847@...
• Name+digits — alice847@...
• Noun+digits — thunder291@...
• Random chars — xk9mf2rq8b@...
• Digits only — 8472918384@...
• Letters only — zqxlmnptvr@...

For name-based styles, FreeCustom.Email uses a built-in pool of first names and last names, generating thousands of realistic combinations. You can override these with custom lists or import a .txt file.

Domain Selection

You control which domains your generated inboxes land on:

• Any — random across all domains you have access to
• Free only — restricted to free-tier domains
• Pro only — Growth plan and above; pro-tier domains
• My custom domains — your verified custom domains (Growth+)
• Specific domains — you select exactly which domains to use
• Per-domain count — Growth+: generate N inboxes per domain across your pool

Output Format — Building Your Bot's Input File

The generator's output_format parameter lets you define a template for each output line. The default is:

{email}----{otp_url}

Available variables: {email}, {username}, {domain}, {otp_url}, {token}, {api_key}

This means you can generate output that's directly consumable by your bot without any post-processing — one line per inbox, containing exactly the fields your script needs.

You can also download the results as a .txt file from the dashboard UI, or process them directly from the API response JSON.

Token TTL by Plan

The per-inbox token embedded in the OTP URL has a validity period that depends on your plan:

• Developer plan: 7 days (fixed)
• Startup plan: 30 days (fixed)
• Growth plan: 90 days default, up to 365 days (configurable)
• Enterprise plan: 365 days default, up to 365 days (configurable)

For most automation workflows, 30 days is more than sufficient — the OTP URL only needs to be valid long enough to complete the verification step after signup. Long TTLs (90–365 days) are useful for workflows that revisit the same inbox months after initial generation.

Complete Bot Example

Here's the minimal Python pattern for using the Inbox Generator in a bot:

1. POST to /v1/inboxes/generate with your gen API key and desired count

2. Each response inbox has: email, otp_url (pre-signed), formatted (your template output)

3. Use email to sign up on target platform

4. Poll otp_url with GET — no API key needed

5. Read result.otp — the extracted verification code

6. Complete verification — done

The otp_url can be safely stored in a job queue, passed to a worker thread, or written to a file — it contains no secrets beyond the scope of that single inbox.

Frequently Asked Questions

What plan do I need to use the Inbox Generator?

Developer plan and above. The free tier does not include access to the Inbox Generator. See freecustom.email/api/pricing for plan details and batch size limits.

How many inboxes can I generate per call?

Batch limits scale by plan. Developer plan supports smaller batches; Growth and Enterprise plans support larger batches and per-domain count mode (N inboxes per domain across your entire domain pool).

Does the OTP URL expire?

The token embedded in the OTP URL expires after the TTL set by your plan (7 days on Developer, up to 365 days on Growth/Enterprise). After expiry, polling the URL returns an error. For most bot workflows, the URL only needs to be valid for minutes to hours.

Can I use my own domain for generated inboxes?

Yes — Growth plan and above supports verified custom domains. Generated inboxes can land on your own domain, which can improve deliverability for verification emails from services that validate the recipient domain.

What does parseCode=true do?

It instructs the OTP endpoint to parse the email body and subject, extract numeric codes in the 4–8 digit range, and return them in the otp field. Without it, the endpoint returns otp: null for API inboxes and you'd need to parse the raw email content yourself.

Conclusion

The FreeCustom.Email Inbox Generator is purpose-built for automation: bulk generation, pre-signed OTP URLs, auto-extraction, and long-polling in a single API endpoint. If you're building anything that needs to handle email verification at scale, this is the tool designed for exactly that workflow.

Visit the API dashboard to access the Inbox Generator tab, generate your gen API key, and start building. Full documentation is available at freecustom.email/api.