API Documentation

Base URL:

Base API Host

https://api.afhamxmailz.com

How to Use Our API (It's Easy!)

Our API is flexible! Choose FREE access (with a slight delay) or SUBSCRIBE for instant access.

Public API: Accessing General Email Data

Endpoints like /domains or /inbox/generate have two modes:

Standard Speed: API key required, with standard processing queue to ensure fair usage for everyone.
Lightning Fast (Subscribed Users): Use your API key in the X-API-KEY header. This gives you instant responses and higher limits based on your subscription plan.

header payload

X-API-KEY: your_subscription_api_key_here

Authentication & API Access

Configure access modes to customize data processing speed or interact with private, account-specific inboxes.

Public API: Free (Standard) or Instant (Priority)

Use this for general email data. Free tier access is processed at standard speed. Subscribe for instant, priority access with higher rate limits.

Bearer Token (for Private Endpoints)

Use the Authorization: Bearer <token> header for private endpoints (e.g. modifying your synced user inboxes). Generate this token in your dashboard or retrieve it upon signing in.

authorization header

Authorization: Bearer your_generated_dashboard_token_here

The Bearer token links the API request directly to your user account, allowing access to private addresses owned by you.

How to Obtain an API Key

API keys are available to all users. Note: instant/no-delay access is only granted when the API key is linked to an active paid subscription plan - otherwise requests are treated as public (subject to standard speed and free-tier rate limits).

Access Settings

Click the settings gear icon in the navigation bar to pull open your account configuration.

Generate API Key

Scroll to the "Developer API Keys" panel, type a nickname, and click "Create". Copy your key.

API Rate Limits & Features

Free tier has limits, subscriptions unlock higher performance. Our API requires an API key for all access. The free tier runs at standard processing speed on every request and rate limits apply. Subscribers get instant access with higher rate limits:

Plan	Pricing	Features / Processing Rate
Free Tier	$0/month	5 reqs/sec rate limit, 1 active inbox, 10-minute inbox expiry
Pro Plan	$2.99/month	50 reqs/sec rate limit, 10 active inboxes, 24-hour expiry, custom usernames, subdomain support
Ultra Plan	$6.99/month	Unlimited rate limit, unlimited active inboxes, 30-day expiry, custom domains, webhooks enabled

Webhooks

Get HMAC-SHA256-signed POSTs at your endpoint whenever a message lands in one of your inboxes. Webhooks are part of the Ultra tier ($6.99/mo). Team owners and members get them too.

Event Types

message.received	A new email lands in one of your active inboxes.
inbox.created	A new inbox was provisioned on your account.
test.ping	Fired from dashboard verification button.

Request Headers

webhook headers

X-AfhamXMail-Signature: sha256=<hmac_hex>
X-AfhamXMail-Event: email.received
X-AfhamXMail-Delivery: <unique_id>
X-AfhamXMail-Timestamp: <unix_seconds>
Content-Type: application/json

JSON Payload

{
  "event": "email.received",
  "delivery_id": "7c4f...",
  "timestamp": 1731234567,
  "data": {
    "inbox_id": "5d2f...",
    "inbox": "abc@afhamxmailz.com",
    "message_id": "9a1b...",
    "from": "noreply@acme.test",
    "to": ["abc@afhamxmailz.com"],
    "subject": "Your verification code",
    "received_at": "2026-05-17T09:31:00Z",
    "size_bytes": 4732,
    "encrypted": true
  }
}

Verify Signature (Node.js Express webhook route example)

express-webhook.js

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use("/webhooks/afhamxmail", express.raw({ type: "application/json" }));

app.post("/webhooks/afhamxmail", (req, res) => {
  const header = req.header("x-afhamxmail-signature") || "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", process.env.AFHAMXMAIL_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected))) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // ...handle event...
  res.status(200).end();
});

Retry Policy: On 5xx or timeout we retry with exponential backoff (1m, 5m, 30m, 6h). After 10 consecutive failures we auto-pause the webhook.

Official SDKs

Same API surface across all four languages — create_inbox, wait_for_otp, read_messages, etc. Each surfaces structured upgrade prompts when a tier/cap blocks a call.

Error handling is typed in every SDK: Tier-required and cap-related responses (402 / 403 / 429 with upgrade triggers) return a dedicated error carry required_tier, upgrade_url, etc. so you know how to resolve them.

API Endpoints Reference

GET /domains

List available domain names supported by the mail engine. Pro domains require pro tier billing validation.

Authentication

X-API-KEY (Header) or Authorization Bearer

Query Parameters

None required.

loading...

Response

loading...

POST /inbox/generate

Generate a customized or randomized temporary inbox. Authenticated users sync created inboxes to their profiles.

Request Body

Field	Type	Req	Description
domain	string	No	Target domain node. Optional if `type` query parameter is specified.
username	string	No	Customize prefix. If omitted, a randomized name is automatically generated.
subdomain	string	No	Pro/Ultra subdomain routing.

Query Parameters

Param	Type	Req	Description
type	string	No	Target routing type. Pass `discord` to auto-select an active domain configured specifically for Discord.

loading...

Response

loading...

GET /emails/{address}

Fetch summaries of all messages landing in the specified temporary inbox address.

Path Parameters

Param	Type	Req	Description
address	string	Yes	Full inbox address (e.g. user@domain.com)

loading...

Response

loading...

GET /emails/{address}/search

Search emails in a specified temporary inbox for a keyword match in the subject line, body text, or HTML content (case-insensitive).

Path Parameters

Param	Type	Req	Description
address	string	Yes	Full inbox address (e.g. user@domain.com)

Query Parameters

Param	Type	Req	Description
q	string	Yes	The keyword to search for (minimum 1 character)
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 20, max: 100)

loading...

Response

loading...

GET /emails/{address}/sender-domain

Filter emails in a specified temporary inbox by the sender's domain (e.g. only return emails sent from @github.com or @acme.com).

Path Parameters

Param	Type	Req	Description
address	string	Yes	Full inbox address (e.g. user@domain.com)

Query Parameters

Param	Type	Req	Description
domain	string	Yes	The domain of the sender to filter by (e.g., github.com)
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 20, max: 100)

loading...

Response

loading...

GET /emails/message/{id}

Retrieve detailed content, HTML bodies, raw headers, and attachments for a specific message by its unique database ID.

Path Parameters

Param	Type	Req	Description
id	string	Yes	MongoDB BSON ObjectId of the email message.

loading...

Response

loading...

DELETE /emails/message/{id}

Permanently purge a single incoming email message from the database.

Path Parameters

Param	Type	Req	Description
id	string	Yes	ID of the email message to purge.

loading...

Response

loading...

DELETE /inbox/{address}

Permanently delete a specified temporary inbox, purging all email contents and dropping active listener routes.

Path Parameters

Param	Type	Req	Description
address	string	Yes	Full inbox address to release.

loading...

Response

loading...