REST API · v1 · Free

Temporary email,
curl-ready.

Embed disposable email, temporary inbox and OTP detection into your apps in a few lines. Clean REST, clean JSON, open CORS, no auth.

4 endpoints
11 domains
7j retention
0€ cost
Try it now Documentation
01 / Playground

Test it right from your browser

No need for Postman or a terminal. Pick an endpoint, tweak the params, hit run. The actual API response shows up in real-time.

Request
GET https://mail123.fr/api/v1/mailbox/new
Response
Click Execute to run the request…
Request
GET https://mail123.fr/api/v1/mailbox/{address}/messages
Response
Click Execute to run the request…
Request
GET https://mail123.fr/api/v1/mailbox/{address}/messages/{id}
Response
Click Execute to run the request…
Request
GET https://mail123.fr/api/v1/domains

No params. Returns the list of active email domains.

Response
Click Execute to run the request…
02 / Endpoints

4 endpoints, no magic

All endpoints use HTTPS, return UTF-8 JSON, and include X-RateLimit-* headers so you can track your usage.

GET
/api/v1/mailbox/new
Generate a random temporary email address.
5/min · 50/h GET
/api/v1/mailbox/{address}/messages
List received emails. Includes automatic OTP detection.
10/min · 50/h GET
/api/v1/mailbox/{address}/messages/{id}
Get the full content of an email (text, HTML, attachments, OTP).
10/min · 50/h GET
/api/v1/domains
List available email domains.
10/min
03 / Snippets

Copy-paste into your stack

Complete workflow: create a mailbox → poll for emails → extract the OTP code. In your language of choice.

# 1. Créer une boîte ADDR=$(curl -s https://mail123.fr/api/v1/mailbox/new | jq -r '.address') echo "Mailbox: $ADDR" # 2. Poller les emails (toutes les 5s) while true; do RESP=$(curl -s "https://mail123.fr/api/v1/mailbox/$ADDR/messages") OTP=$(echo $RESP | jq -r '.messages[0].otp_code // empty') [ -n "$OTP" ] && echo "OTP: $OTP" && break sleep 5 done
// 1. Créer une boîte const { address } = await fetch('https://mail123.fr/api/v1/mailbox/new').then(r => r.json()) console.log('Mailbox:', address) // 2. Poller toutes les 5s jusqu'à recevoir un OTP async function waitForOTP() { while (true) { const { messages } = await fetch(`https://mail123.fr/api/v1/mailbox/${address}/messages`).then(r => r.json()) const otp = messages.find(m => m.otp_code)?.otp_code if (otp) return otp await new Promise(r => setTimeout(r, 5000)) } } console.log('OTP:', await waitForOTP())
import requests, time # 1. Créer une boîte addr = requests.get('https://mail123.fr/api/v1/mailbox/new').json()['address'] print(f'Mailbox: {addr}') # 2. Poller jusqu'à recevoir un OTP while True: msgs = requests.get(f'https://mail123.fr/api/v1/mailbox/{addr}/messages').json()['messages'] otp = next((m['otp_code'] for m in msgs if m.get('otp_code')), None) if otp: print(f'OTP: {otp}'); break time.sleep(5)
<?php // 1. Créer une boîte $res = json_decode(file_get_contents('https://mail123.fr/api/v1/mailbox/new'), true); $addr = $res['address']; echo "Mailbox: $addr\n"; // 2. Poller jusqu'à OTP while (true) { $msgs = json_decode(file_get_contents("https://mail123.fr/api/v1/mailbox/$addr/messages"), true)['messages']; foreach ($msgs as $m) { if (!empty($m['otp_code'])) { echo "OTP: {$m['otp_code']}\n"; exit; } } sleep(5); }
package main import ("encoding/json"; "fmt"; "net/http"; "time") func main() { // 1. Créer une boîte r, _ := http.Get("https://mail123.fr/api/v1/mailbox/new") var box struct{ Address string } json.NewDecoder(r.Body).Decode(&box) // 2. Poller for { r, _ := http.Get("https://mail123.fr/api/v1/mailbox/" + box.Address + "/messages") var res struct{ Messages []struct{ OtpCode string `json:"otp_code"` } } json.NewDecoder(r.Body).Decode(&res) for _, m := range res.Messages { if m.OtpCode != "" { fmt.Println("OTP:", m.OtpCode); return } } time.Sleep(5 * time.Second) } }
require 'net/http'; require 'json' # 1. Créer une boîte addr = JSON.parse(Net::HTTP.get(URI('https://mail123.fr/api/v1/mailbox/new')))['address'] puts "Mailbox: #{addr}" # 2. Poller jusqu'à OTP loop do msgs = JSON.parse(Net::HTTP.get(URI("https://mail123.fr/api/v1/mailbox/#{addr}/messages")))['messages'] otp = msgs.find { |m| m['otp_code'] }&.dig('otp_code') if otp then puts "OTP: #{otp}"; break end sleep 5 end
04 / Quotas

Free today, Pro soon

The free public API covers most personal and testing use cases. For higher volume or commercial use, a Pro plan is coming.

Free
50 req/h
5 per minute, par IP
  • No API key
  • Open CORS
  • Automatic OTP detection
  • 4 domains available
  • Clean UTF-8 JSON
Pro · Soon
5 000 req/h
API key, support, SLA
  • 150x higher volume
  • Email-received webhooks
  • Custom domain
  • 30-day retention
  • Priority support
05 / Use cases

What developers build with it

Concrete uses of the mail123 API, from e2e tests to marketing automation. All legitimate, all sign-up free.

Automated e2e tests

Playwright, Cypress, Selenium: generate an address on the fly, fill out the form, read the confirmation mail, extract the link or code. Full cycle in 30 seconds.

Bypass email verification

Sign up on sketchy services, throwaway accounts to try a demo, one-shot access to email-walled content — without polluting your main inbox.

Bots & automation

Scrapers that need to pass an email confirm, n8n/Make/Zapier workflows, Selenium scripts that automate onboarding. The API plugs in with 3 lines.

Dev environments

Stage & preview environments: replace Mailtrap, MailHog or SES with a public API. Devs see real emails without configuring SMTP.

Tutorials & courses

Webhook demos, OAuth exercises, security training: a throwaway public address lets learners test safely without risking their real inbox.

Privacy tools

Browser extensions, password managers, anti-spam tools: integrate alias generation in a single HTTP call.

06 / Errors

HTTP codes & error handling

All responses include a success: bool field and an optional error: string. HTTP codes follow REST conventions.

CodeMeaningAction
200SuccessResponse includes success: true
400Bad RequestCheck syntax of the address or parameter
403ForbiddenReserved address (admin, root, postmaster…)
404Not FoundEmail not found or expired
429Too Many RequestsWait 1 minute, or retry after the reset
500Server ErrorServer error — retry, otherwise contact support
07 / FAQ

Frequently asked questions

Answers to the questions developers ask us most.

Is the API really free?
Yes, completely free. No credit card, no sign-up, no hidden limits. 30 requests per hour per IP covers most personal and test usage. For more, the Pro plan is coming soon.
Do I need an API key?
No. The public API works without authentication. For Pro (coming soon), an X-API-Key header will unlock higher limits.
Does the API support CORS?
Yes, CORS is fully open (Access-Control-Allow-Origin: *). You can call the API directly from a browser in JavaScript, without a proxy.
How long are emails kept?
Mailboxes and their emails are automatically deleted after 7 days of inactivity. No persistent storage, no archive, no user profile.
Does the API detect OTP codes automatically?
Yes. Every returned message includes an otp_code field. Our extractor recognizes numeric codes (4-8 digits), alphanumeric, and separator formats (XX-XX, XX XX). Context-aware: the score boosts when keywords like "verification", "code", "OTP" are nearby.
Which email domains are available?
Currently active domains: mail123.frmail456.frmail789.frmail123.cloudmail1mail.commail123.ptmail123.clickmaildaft.commail123.com.brdaftmail.cloudmailtemp.fr. Live list via GET /api/v1/domains.
Does the API support webhooks?
Not yet. The current version requires polling (GET /messages every 5-10 seconds). Webhooks are planned in Pro: HTTPS push notifications when emails arrive in mailboxes you watch.
What happens if I hit the rate limit?
The API returns HTTP 429 with a Retry-After header indicating in seconds when to retry. X-RateLimit-Remaining and X-RateLimit-Reset headers let you monitor usage upstream.
What uses are allowed?
Any legitimate use: automated tests, sandbox account verification, dev workflow automation, privacy tools. Abuse (spam, mass scraping, fraud) results in a permanent IP block without notice.
Is the service reliable? What uptime?
The service runs on OVH servers in Roubaix, France, with 99.95% average uptime over the last 12 months. Real-time status at status.mail123.fr.

Build something cool

No signup. No credit card. No webhook config. Make your first API call in 10 seconds.

Try it now See the widget too