Developer API

Create temporary inboxes and read their mail from your own code. Base URL: https://siteindex.cc/api/v1. All responses are JSON with the shape {"ok": true, "data": …} or {"ok": false, "error": "…"}.

Authentication

Your first wallet top-up of at least $2.00 unlocks the API. Create keys in Dashboard → API keys and send them as a bearer token. Keys are shown once; we only store a hash.

Authorization: Bearer pim_4f2c…

A disputed or refunded payment suspends the account and revokes every key.

Inboxes

Request	What it does
`GET /api/v1/inbox?action=domains`	Domains with your effective price per address.
`GET /api/v1/inbox?action=account`	Balance and account state.
`POST /api/v1/inbox`	Create an inbox. Body: {"domain": "…", "local_part": "optional"}. Pro domains are charged to your wallet.
`GET /api/v1/inbox`	List your inboxes, newest first.
`GET /api/v1/inbox/{id}`	One inbox with delivery and refund status.
`DELETE /api/v1/inbox/{id}`	Cancel. An empty Pro inbox at least 2 minutes old is refunded.

curl -X POST https://siteindex.cc/api/v1/inbox \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"domain":"pro.example.com","local_part":"signup-test-17"}'

{
  "ok": true,
  "data": {
    "inbox": {
      "id": 42, "address": "signup-test-17@pro.example.com", "status": "active",
      "paid_amount": "0.20", "delivered": false,
      "refund": { "guaranteed": true, "refunded": false, "refund_deadline": "…", "seconds_until_refund": 600 }
    },
    "recovery_token": "PIR-…", "charged": "0.20", "balance": "1.80"
  }
}

Messages

Request	What it does
`GET /api/v1/messages?inbox_id=42&since_id=0`	Messages (newest first) plus the inbox status. Pass the highest id you have as since_id to fetch only new mail.
`GET /api/v1/messages/{id}`	Full message: text, HTML (links masked), detected one-time code, attachments.
`GET /api/v1/messages/{id}?format=eml`	Raw RFC 822 source.
`GET /api/v1/messages?attachment_id=7`	Download an attachment.
`DELETE /api/v1/messages/{id}`	Delete a message.

# Python — wait for a verification code
import requests, time
H = {"Authorization": "Bearer " + KEY}
while True:
    r = requests.get("https://siteindex.cc/api/v1/messages", params={"inbox_id": 42}, headers=H).json()
    codes = [m["otp"] for m in r["data"]["messages"] if m["otp"]]
    if codes: print(codes[0]); break
    time.sleep(2)

Delivery guarantee

If a Pro inbox receives no message within 10 minutes, its price returns to your wallet automatically. The inbox then reports status "refunded_no_mail" and refund.refunded = true, and an inbox.refunded webhook is sent for inboxes created through the API.

Webhooks

Register HTTPS endpoints in Dashboard → Webhooks. Events: message.received, inbox.refunded. Each request carries an X-PostInbox-Signature header: t=<unix time>,v1=<hex HMAC-SHA256 of "t.body" with your webhook secret>.

<?php // verify in PHP
[$t, $v1] = array_map(fn($p) => explode('=', $p, 2)[1], explode(',', $_SERVER['HTTP_X_POSTINBOX_SIGNATURE']));
$body = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $t . '.' . $body, $secret), $v1) && abs(time() - (int)$t) < 300;

Errors and limits

Status	Meaning
401	Missing, malformed or revoked key.
402	Not enough balance for a Pro address — top up your wallet.
403	API not unlocked yet, or the account is suspended.
409	That address is taken.
425	Too early to cancel — wait until the inbox is 2 minutes old.
429	Rate limit reached. Respect the Retry-After header.