FreeGmail API Docs — Temp Email & OTP API Reference

API Reference

Base URL https://freegmail.com/api/public/v1. Authenticate every request with Authorization: Bearer YOUR_KEY (or X-API-Key).

12,000

Gmail in stock

15,000

Outlook in stock

27,000+

Total live

JavaScript quick start

const r = await fetch("https://freegmail.com/api/public/v1/inboxes", {
  method: "POST",
  headers: { Authorization: "Bearer fg_live_YOUR_KEY",
             "Content-Type": "application/json" },
  body: JSON.stringify({ service: "gmail_alias" }),
});
const inbox = await r.json();

Python quick start

import requests
r = requests.post("https://freegmail.com/api/public/v1/inboxes",
  headers={"Authorization": "Bearer fg_live_YOUR_KEY"},
  json={"service": "outlook_alias"})
inbox = r.json()

POST/v1/inboxes— Create inbox

Creates a new temporary inbox (expires after 10 minutes). Body: { "service": "gmail_alias" | "outlook_alias" | "gmail_original" | "outlook_original" } — Gmail.com + Alias, Outlook.com + Alias, Gmail.com Original, Outlook.com Original. List availability and prices with GET /v1/services.

Request

curl -X POST https://freegmail.com/api/public/v1/inboxes \
  -H "Authorization: Bearer fg_live_YOUR_KEY"

Response

{ "id": "8f1c…", "address": "name+abc@outlook.com", "expires_at": "…", "created_at": "…" }

GET/v1/inboxes/{id}/messages— Poll inbox

Fetches new mail and returns the list of messages with the detected OTP.

Request

curl https://freegmail.com/api/public/v1/inboxes/INBOX_ID/messages \
  -H "Authorization: Bearer fg_live_YOUR_KEY"

Response

{ "inbox": { "id": "…", "address": "…", "active": true }, "data": [ { "id": "…", "from": "…", "subject": "…", "otp": "482913", "received_at": "…" } ] }

GET/v1/messages/{id}— Read message

Returns the full message (text + HTML) for a message from one of your inboxes.

Request

curl https://freegmail.com/api/public/v1/messages/MESSAGE_ID \
  -H "Authorization: Bearer fg_live_YOUR_KEY"

Response

{ "id": "…", "to": "…", "from": "…", "subject": "…", "text": "…", "html": "…", "otp": "482913" }

GET/v1/account/*— Balance & usage (no charge)

Check your wallet balance and the last 100 requests.

Request

curl https://freegmail.com/api/public/v1/account/balance -H "Authorization: Bearer fg_live_YOUR_KEY"
curl https://freegmail.com/api/public/v1/account/usage -H "Authorization: Bearer fg_live_YOUR_KEY"

Response

{ "balance": 104998, "currency": "credits" }

Error codes

401unauthorizedMissing, invalid or revoked key
402insufficient_creditsAdd funds to your wallet
403suspendedAccount under review
404not_foundInbox/message not yours, or unknown endpoint
429rate_limitedToo many requests per minute
502upstream_errorMail service failed (not charged)