PHMail Developer API

A small REST API for automated, legitimate software and QA testing — registration flows, password resets, OTP/verification testing. Base URL https://phmail.space/v1. All responses are JSON.

Authentication

Send your key as a Bearer token. Keys start with phm_live_ and are shown once at creation. Only active PHMail Developer subscriptions may call the API.

Authorization: Bearer phm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create Inbox

POST /v1/inboxes — creates an isolated developer inbox (not publicly readable). Optional JSON body {"address":"myname"}; omit to auto-generate.

curl -X POST https://phmail.space/v1/inboxes \
  -H "Authorization: Bearer phm_live_..." \
  -H "Content-Type: application/json" -d '{"address":"qa-signup"}'

{ "data": { "id": "inb_1a2b3c...", "address": "qa-signup@inbox.phmail.space",
  "created_at": "2026-08-01T00:00:00+00:00", "expires_at": "2026-08-08T00:00:00+00:00" } }

List Messages

GET /v1/inboxes/{id}/messages

curl https://phmail.space/v1/inboxes/inb_1a2b3c/messages \
  -H "Authorization: Bearer phm_live_..."

Retrieve Message

GET /v1/messages/{inbox_id}/{message_id} — includes a detected verification_code when present (extracted locally).

// JavaScript (fetch)
const r = await fetch("https://phmail.space/v1/messages/inb_1a2b3c/42", {
  headers: { Authorization: "Bearer phm_live_..." }
});
const { data } = await r.json();
console.log(data.verification_code);

{ "data": { "id": 42, "from": "accounts@example.com", "subject": "Your code",
  "verification_code": "483921", "received_at": "2026-08-01T00:00:00+00:00" } }

Delete Inbox

DELETE /v1/inboxes/{id}

<?php // PHP
$ch = curl_init("https://phmail.space/v1/inboxes/inb_1a2b3c");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => ["Authorization: Bearer phm_live_..."],
  CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);

Usage

GET /v1/usage — month-to-date counts and your plan limits.

{ "data": { "requests": { "used": 3421, "limit": 10000 },
  "inboxes_created": { "used": 284, "limit": 1000 } } }

Errors

Errors return { "error": { "code", "message" } } with an appropriate HTTP status:

• 401 UNAUTHORIZED — missing, invalid or revoked key
• 403 PLAN_REQUIRED — key's account is not on the Developer plan
• 404 NOT_FOUND — inbox/message not found or not owned by you
• 429 RATE_LIMITED / QUOTA_EXCEEDED — short-window or monthly limit hit

Rate Limits

Per key: 120 requests / 60 seconds. Per account: 10,000 requests and 1,000 inbox creations per calendar month (configurable per plan). Exceeding returns 429 with Retry-After where applicable.

Never embed real API keys in client-side code or documentation. Rotate keys you believe are exposed.