TempGBox API

Generate temporary email aliases and read inbox messages from your own code.

REST API

Generate aliases and read inbox messages programmatically with a simple X-API-Key header. Available to every signed-in account, free or Premium.

Real-time webhooks

Register an HTTPS endpoint and get an HMAC-signed POST the instant a new message lands in one of your aliases. Premium only.

Keys expire automatically

Free keys auto-expire after 7 days; Premium keys after 30 days (matching the Premium billing cycle) — renew anytime by creating a new one. Free accounts get 1 active key; Premium gets up to 5, plus up to 5 webhooks.

Example — generate an alias

curl -X POST https://tempgbox.net/api/mailbox/generate/ \
  -H "X-API-Key: tgbx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"variant": "random"}'

How to get and use a key

Sign in (free or Premium — a free account works fine to get started) and scroll down to Your API keys below.
Click Create key, optionally naming it (e.g. "production server").
Copy the raw key immediately — it's shown only once and can't be retrieved again after you leave the page.
Send it on every request as an X-API-Key header, as in the example above.
Key stops working, or need higher limits? Revoke it below and create a new one — keys also auto-expire on their own (7 days Free, 30 days Premium).

Rate limits & plans

Plan	Requests	Active keys	Key expiry
Free	100 requests/day	1 active key	7 days
Premium	10,000 requests/day	5 active keys	30 days (billing cycle)

Endpoints

POST/api/mailbox/generate/Auth: X-API-Key

Generate a new temporary email alias.

Param	Type	Description
variant	string	Alias style. Default "random" (mixes Gmail variants and custom domains).
domain_id	integer	Use a specific custom domain instead of the random pool.
custom_username	string	Requested local part — requires domain_id.

curl -X POST https://tempgbox.net/api/mailbox/generate/ \
  -H "X-API-Key: tgbx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"variant": "random"}'

201 Response

{
  "alias": {
    "id": 600,
    "alias": "[email protected]",
    "email": "[email protected]",
    "created_at": "2026-08-18T14:23:05Z",
    "expires_at": "2026-08-19T14:23:05Z",
    "is_active": true,
    "is_expired": false,
    "total_emails_received": 0
  },
  "message": "Alias generated successfully"
}

429 Response

{
  "error": "Daily alias limit reached (100 per day)"
}

GET/api/mailbox/inbox/Auth: X-API-Key

Get messages received by an alias you own — up to 50, newest first.

Param	Type	Description
email*	string	The full alias address, as a query parameter.

curl "https://tempgbox.net/api/mailbox/inbox/[email protected]" \
  -H "X-API-Key: tgbx_your_key_here"

200 Response

{
  "alias": { "email": "[email protected]", "is_active": true, "is_expired": false },
  "messages": [],
  "total": 0
}

404 Response

{
  "error": "Alias not found or expired",
  "email": "[email protected]"
}

GET/api/mailbox/my-emails/Auth: X-API-Key

List every active alias tied to your account.

curl https://tempgbox.net/api/mailbox/my-emails/ \
  -H "X-API-Key: tgbx_your_key_here"

200 Response

{
  "count": 1,
  "results": {
    "aliases": [
      { "id": 600, "email": "[email protected]", "is_active": true, "total_emails_received": 0 }
    ],
    "total": 1
  }
}

401 Response

{
  "detail": "This API key has expired. Generate a new one from /developers."
}

POST/api/mailbox/delete/Auth: X-API-Key

Deactivate an alias you own.

Param	Type	Description
email*	string	The full alias address to delete.

curl -X POST https://tempgbox.net/api/mailbox/delete/ \
  -H "X-API-Key: tgbx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

200 Response

{
  "message": "Email deleted successfully",
  "email": "[email protected]"
}

400 Response

{
  "error": "Email address is required"
}

Error codes

400	Missing or invalid request parameters.
401	API key is missing, invalid, revoked, or expired — generate a new one below.
403	Blocked by an automated-traffic check (send a real User-Agent header), or the endpoint needs an active Premium plan.
404	Alias not found, expired, or not owned by this key.
429	Rate limit exceeded — 100 requests/day (Free) or 10,000/day (Premium).

Verifying a webhook (Premium)

Every delivery is a POST with an X-TempGBox-Signature header — an HMAC-SHA256 hex digest of the raw request body, signed with the secret shown when you registered the endpoint. Verify it before trusting the payload:

// Node.js — verify X-TempGBox-Signature on an incoming webhook POST
const crypto = require('crypto')

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}