Temporary Email API

1. Create an account and open Dashboard → API.
2. Create and save an API key.
3. Create a mailbox with POST /v1/mailboxes.
4. Send mail to the returned address.
5. Use a Wait API or signed Webhook to consume it.

curl -X POST https://aigeneratoremail.com/v1/mailboxes \
  -H "Authorization: Bearer aieg_live_..." \
  -H "Idempotency-Key: signup-test-42" \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds":3600}'

Create one mailbox or a batch of up to 100. Cumulative mailbox count is unlimited; requests, received mail, and abuse controls follow the active plan.

Send a unique Idempotency-Key (maximum 255 characters) on create requests. An identical retry within 24 hours returns the original status and body with Idempotent-Replayed: true. Reusing the key with different input returns HTTP 409 IDEMPOTENCY_KEY_REUSED.

DELETE /v1/mailboxes/{mailboxId} permanently removes the mailbox, its messages, attachments, and stored MIME objects.

Message details include text, sanitized HTML, headers, attachments, raw MIME, verification codes, verification links, and authentication links. Messages above 25 MB are rejected.

Temporary-email message records, attachments, and raw MIME are permanently deleted after 7 days on every plan. Mailbox recovery restores the address and its ability to receive new email; it does not restore deleted message content.

The signing secret is returned only by the create response. Save it immediately; later list responses never expose the secret, its hash, or encrypted storage value.

Verify x-aieg-signature against the exact body and reject timestamps older than five minutes. Deliveries use exponential retries, dead-letter state, logs, tests, and manual replay. Deleting a Webhook also deletes its delivery history.

For a subdomain, authorize the Cloudflare account that contains its parent Zone. The installer enables Email Routing DNS records for the full subdomain, so existing MX records on the parent domain are not replaced. To protect existing mail flows, setup stops if that Cloudflare Zone already has an unrelated catch-all routing rule.

1. Back up A, AAAA, CNAME, MX, TXT, CAA, SPF, DKIM, and DMARC records.
2. Add the parent domain to Cloudflare and compare the DNS scan with the backup.
3. Preserve Google, Microsoft, Zoho, or other production email records on the parent domain.
4. Disable registrar DNSSEC before changing Nameservers.
5. Apply Cloudflare’s two Nameservers and wait for Active status.
6. Verify the website and production email, then re-enable DNSSEC.
7. Return to Custom Domains and add a dedicated receiving subdomain such as testmail.example.com.
8. Select Verify DNS, authorize its parent Cloudflare Zone, and wait for the subdomain to become Active.

Message retention is fixed at 7 days for Free, Developer, Pro, and Scale. Stacked subscriptions increase additive quotas but do not extend message storage.

Successful JSON responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A minute-rate 429 also includes those headers and Retry-After. Respect Retry-After before retrying; otherwise use bounded exponential backoff for transient 5xx responses.

HTTP/2 429
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783919460
Retry-After: 23

{"error":{"code":"RATE_LIMIT_EXCEEDED","message":"Too many API requests...","details":{"retryAfter":23}},"requestId":"..."}

Errors contain a stable code, message, optional details, and request ID. Include the request ID when contacting support.