API Documentation

Base URL:
Base API Host
https://api.afhamxmailz.com
Free tier has rate limits. Get a paid plan if you need more.

How to use the API

Our API is straightforward. Free tier works fine for most things, paid plans get higher rate limits.

Public API: Accessing General Email Data

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

  • Free Tier: API key required, subject to free-tier rate limits.
  • Paid Plans: Use your API key in the X-API-KEY header for higher rate limits based on your subscription plan.
header payload
X-API-KEY: your_subscription_api_key_here

Authentication & API Access

Use an API key for higher rate limits, or a Bearer token to access your own private inboxes.

Public API

Use this for general email data. Free tier has rate limits. Paid plans get higher 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

Bearer token ties the request to your account.

How to Obtain an API Key

API keys are available to all users. Free tier keys are subject to rate limits. Paid plan keys get higher limits.

1
Login to Your Account
Sign in to your AfhamXMail account using your email and password.
2
Access Settings
Click the settings gear icon in the navigation bar to pull open your account configuration.
3
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 rate limits. Paid plans get higher limits. Here's the breakdown:

Plan Pricing Features / Processing Rate
Free Tier $0/month 5 reqs/sec rate limit, 5 active inboxes, 24-hour inbox expiry, custom usernames
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
Free tier is always available

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).

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": "[email protected]",

    "message_id": "9a1b...",

    "from": "[email protected]",

    "to": ["[email protected]"],

    "subject": "Your verification code",

    "received_at": "2026-05-17T09:31:00Z",

    "size_bytes": 4732,

  }

}

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();

});

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

Param Type Req Description
type string No Filter domains by type (e.g. discord, google, general) 
loading...
Response 200 OK
loading...
POST /inbox/generate

Create a temp inbox. If you're logged in, it gets saved to your account.

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.
username_length integer No Generate a random username of the specified length (between 4 and 20). Ignored if username is provided.
password string No Optional password protection for the created inbox. When set, reading messages requires passing this password in query parameter password or HTTP header X-Inbox-Password.

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 201 Created
loading...
GET /inbox

List all active temporary inboxes associated with your developer account.

Query Parameters

No parameters required. Authenticate using your API key.

loading...
Response 200 OK
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. [email protected])

Query Parameters

Param Type Req Description
page integer No Page number for pagination (default: 1)
per_page integer No Results per page (default: 20, max: 100)
unread_only boolean No Filter to only show unread messages (default: false)
password string No Required if the target inbox is password-protected. Alternatively, pass in HTTP header X-Inbox-Password. 
loading...
Response 200 OK
loading...
GET /emails/{address}/wait

Long-polling connection. Holds the connection open and returns new emails instantly when they arrive. Ideal for scripts waiting for confirmation or verification codes.

Path Parameters

Param Type Req Description
address string Yes Full inbox address (e.g. [email protected])

Query Parameters

Param Type Req Description
timeout integer No Seconds to wait before timing out (default: 30, max: 60) 
loading...
Response 200 OK
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. [email protected])

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 200 OK
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. [email protected])

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 200 OK
loading...
GET /emails/message/{id}

Get the full content of a message - subject, body, headers.

Path Parameters

Param Type Req Description
id string Yes MongoDB BSON ObjectId of the email message. 
loading...
Response 200 OK
loading...
PATCH /emails/message/{id}/read

Mark a single email message as read.

Path Parameters

Param Type Req Description
id string Yes ID of the email message to mark as read. 
loading...
Response 204 No Content
loading...
DELETE /emails/message/{id}

Delete a single email.

Path Parameters

Param Type Req Description
id string Yes ID of the email message to purge. 
loading...
Response 204 No Content
loading...
DELETE /inbox/{address}

Permanently delete a temporary inbox and all its emails.

Path Parameters

Param Type Req Description
address string Yes The inbox address to delete. 
loading...
Response 204 No Content
loading...
DELETE /inbox

Permanently delete all temporary inboxes and their emails associated with your developer account in one single operation.

Query Parameters

No parameters required. Authenticate using your API key.

loading...
Response 204 No Content
loading...