ALIGHTMAIL
← Inbox alightmotionmail.web.id

API Documentation

JSON API for creating mailboxes and reading incoming messages. All endpoints require an API key.

Base URL
https://alightmotionmail.web.id/api

Authentication

Every endpoint requires an API key — except health.

Send the key in a header

All authenticated requests must include your API key in the X-API-Key header.

X-API-Key: YOUR_API_KEY

bash
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://alightmotionmail.web.id/api/stats"
If the key is missing or wrong, the API returns HTTP 401 with an error body.

Response format

Every response follows one of two shapes.

Success
json
{
  "success": true,
  "data": { /* payload */ },
  "meta": { "time": "2026-10-16T01:20:54+00:00" }
}
Error
json
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_KEY",
  "meta": { "time": "2026-10-16T01:20:54+00:00" }
}

List domains

GET /api/domains

Returns the list of domains available for creating mailboxes.

Request
bash
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://alightmotionmail.web.id/api/domains"
Response
json
{
  "success": true,
  "data": { "domains": ["alightmotionmail.web.id"] },
  "meta": { "time": "..." }
}

Generate address

GET /api/generate

Creates a random address using the pattern 5 letters + 4 digits and registers it automatically.

Query parameter
domain
string
Optional. Defaults to the first configured domain.
Response
json
{
  "success": true,
  "data": { "address": "kfqmx2847@alightmotionmail.web.id" },
  "meta": { "time": "..." }
}

Create mailbox

POST /api/mailbox

Registers a specific address. Safe to call repeatedly — returns success even if the address already exists.

Body parameter
address
string
Full email address.required
Request
bash
curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"hello@alightmotionmail.web.id"}' \
  "https://alightmotionmail.web.id/api/mailbox"

List emails

GET /api/emails?address=...

Returns the most recent emails for a mailbox, newest first. Up to 100 results, with total count in meta.

Query parameters
address
string
Target email address.required
limit
int
Max results (1–100). Default 100.
offset
int
Pagination offset. Default 0.
Response
json
{
  "success": true,
  "data": {
    "address": "hello@alightmotionmail.web.id",
    "emails": [{
      "id": "a1b2c3d4e5f60718",
      "from_address": "sender@gmail.com",
      "subject": "Hello",
      "preview": "First 150 characters...",
      "received_at": "2026-10-16 01:20:54",
      "is_read": false,
      "has_attachments": false
    }]
  },
  "meta": { "total": 1, "limit": 100, "offset": 0, "time": "..." }
}

Email detail

GET /api/email?id=...

Full content of a single email including HTML body, plain text, and attachments. Marks the email as read.

Query parameter
id
string
Email ID (16-char hex).required
Response
json
{
  "success": true,
  "data": {
    "email": {
      "id": "a1b2c3d4e5f60718",
      "from_address": "sender@gmail.com",
      "to_address": "hello@alightmotionmail.web.id",
      "subject": "Hello",
      "body": "Plain text...",
      "html": ",
      "attachments": [],
      "received_at": "2026-10-16 01:20:54",
      "is_read": true
    }
  },
  "meta": { "time": "..." }
}

Delete email

DELETE /api/email?id=...

Permanently deletes a single email. Returns 404 if the ID does not exist.

Response
json
{
  "success": true,
  "data": { "deleted": 1 },
  "meta": { "time": "..." }
}

Clear inbox

DELETE /api/emails?address=...

Deletes every email in a mailbox. The mailbox itself is kept.

Response
json
{
  "success": true,
  "data": { "deleted": 3 },
  "meta": { "time": "..." }
}

Stats

GET /api/stats

Global counters for the service.

json
{
  "success": true,
  "data": { "total_emails": 42, "total_mailboxes": 17 },
  "meta": { "time": "..." }
}

Health

GET /api/health

Public endpoint — no API key required. Useful for uptime monitoring.

json
{
  "success": true,
  "data": { "ok": true, "service": "mailbox-api" },
  "meta": { "time": "..." }
}

Error codes

Error code strings
MISSING_KEY
401
No API key was supplied.
INVALID_KEY
401
API key does not match.
MISSING_ADDRESS
400
Required address parameter missing.
INVALID_ADDRESS
400
Address format or domain not allowed.
NOT_FOUND
404
Requested email does not exist.
METHOD_NOT_ALLOWED
405
Wrong HTTP method for this endpoint.
UNKNOWN_ACTION
404
Unknown action value.

Full examples

End-to-end flow: generate, read, delete.

bash
# Set your key once
KEY="YOUR_API_KEY"
BASE="https://alightmotionmail.web.id/api"

# 1. Generate address
ADDR=$(curl -s -H "X-API-Key: $KEY" "$BASE/generate" | jq -r .data.address)
echo "Address: $ADDR"

# 2. List emails
curl -s -H "X-API-Key: $KEY" "$BASE/emails?address=$ADDR" | jq

# 3. Read one email
curl -s -H "X-API-Key: $KEY" "$BASE/email?id=ID" | jq

# 4. Delete one email
curl -X DELETE -H "X-API-Key: $KEY" "$BASE/email?id=ID"

# 5. Clear inbox
curl -X DELETE -H "X-API-Key: $KEY" "$BASE/emails?address=$ADDR"
JavaScript
javascript
const KEY  = "YOUR_API_KEY";
const BASE = "https://alightmotionmail.web.id/api";

async function api(path, options = {}) {
  options.headers = Object.assign({
    "X-API-Key": KEY,
    "Content-Type": "application/json"
  }, options.headers || {});
  const r = await fetch(BASE + path, options);
  return r.json();
}

// Generate
const gen = await api("/generate");
const address = gen.data.address;

// List
const list = await api(`/emails?address=${encodeURIComponent(address)}`);
console.log(list.data.emails);
Python
python
import requests

KEY  = "YOUR_API_KEY"
BASE = "https://alightmotionmail.web.id/api"
H    = {"X-API-Key": KEY}

# Generate
r = requests.get(BASE + "/generate", headers=H).json()
address = r["data"]["address"]
print(f"Address: {address}")

# List emails
r = requests.get(BASE + "/emails", params={"address": address}, headers=H).json()
for e in r["data"]["emails"]:
    print(e["from_address"], e["subject"])