Vaultmail API

API Reference

A typed REST API for buying long-term addresses and reading their inboxes. All responses are JSON. Money is expressed in integer micro-USD (1 USD = 1,000,000).

Introduction

The public API is served under /v1 on the same origin as your dashboard. Every request must be made over HTTPS. Amounts such as prices and balances are integers in micro-USD; divide by 1,000,000 for a USD value (the default price is 2000 micros = $0.002).

Authentication

Authenticate with an API key created in your dashboard under Security → API keys. Pass it as a Bearer token. Keys are shown only once at creation. Store them securely.

cURL

curl https://api.example.com/v1/products \
  -H "Authorization: Bearer vm_live_your_api_key"

Errors

All failures use a single JSON envelope with a stable machine-readable code and a human-readable message. HTTP status codes follow standard conventions.

json

{
  "error": {
    "code": "insufficient_stock",
    "message": "Not enough addresses available."
  }
}

`insufficient_stock`	Not enough addresses to fulfill the order.
`insufficient_balance`	Your balance is too low for this order.
`unauthorized`	Missing or invalid API key.
`not_found`	The requested resource does not exist.
`rate_limited`	Too many requests. Retry after the given delay.

Rate limits

The public API allows 60 requests per minute per API key, and orders are limited to 10 per minute per user. Requests that exceed a limit receive a 429 with a Retry-After header.

Endpoints

List products

GET/v1/products

Returns both products with their current price (micro-USD) and live stock.

Request

cURL

curl https://api.example.com/v1/products \
  -H "Authorization: Bearer $KEY"

Response

json

{
  "products": [
    { "product": "outlook", "price_micros": 2000, "stock": 4820 },
    { "product": "hotmail", "price_micros": 2000, "stock": 3164 }
  ]
}

Get balance

GET/v1/balance

Returns your current prepaid balance in micro-USD.

Request

cURL

curl https://api.example.com/v1/balance \
  -H "Authorization: Bearer $KEY"

Response

json

{ "balance_micros": 18640000 }

Create order

POST/v1/orders

Purchases addresses of a product. Send an Idempotency-Key header to safely retry; the original order is returned on retry.

Parameters

`product`required	string	"outlook" or "hotmail".
`quantity`required	integer	Number of addresses to buy.

Request

cURL

curl -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: 6f1c-..." \
  -H "Content-Type: application/json" \
  -d '{"product":"outlook","quantity":3}'

Response

json

{
  "order_id": "ord_7c1Ka9",
  "addresses": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

List orders

GET/v1/orders

Returns your order history, most recent first.

Request

cURL

curl https://api.example.com/v1/orders \
  -H "Authorization: Bearer $KEY"

Response

json

[
  {
    "id": "ord_7c1Ka9",
    "product": "outlook",
    "quantity": 5,
    "unit_price_micros": 2000,
    "total_micros": 10000,
    "created_at": "2026-09-14T10:22:00Z"
  }
]

List addresses

GET/v1/addresses

Returns the addresses you own with their current status.

Request

cURL

curl https://api.example.com/v1/addresses \
  -H "Authorization: Bearer $KEY"

Response

json

[
  { "address": "[email protected]", "product": "outlook", "status": "active" },
  { "address": "[email protected]", "product": "hotmail", "status": "active" }
]

List messages

GET/v1/addresses/{address}/messages

Returns messages for an address, newest first, with cursor pagination. Filter by unread, a text query, and a since timestamp.

Parameters

`since`	string (ISO 8601)	Only messages received at or after this time.
`q`	string	Full-text filter over sender, subject, and preview.
`unread`	boolean	Return only unread messages.
`limit`	integer	Maximum messages to return.
`cursor`	string	Pagination cursor from a previous response.

Request

cURL

curl "https://api.example.com/v1/addresses/[email protected]/messages?unread=true&limit=20" \
  -H "Authorization: Bearer $KEY"

Response

json

{
  "messages": [
    {
      "id": "msg_aurora_0",
      "from": "GitHub <[email protected]>",
      "subject": "Your verification code is 481920",
      "preview": "Enter this code to finish signing in.",
      "received_at": "2026-09-16T09:12:00Z",
      "is_read": false
    }
  ],
  "next_cursor": null
}

Get message

GET/v1/addresses/{address}/messages/{id}

Returns the full message, including HTML and text bodies and a subset of headers.

Request

cURL

curl https://api.example.com/v1/addresses/[email protected]/messages/msg_aurora_0 \
  -H "Authorization: Bearer $KEY"

Response

json

{
  "id": "msg_aurora_0",
  "from": "GitHub <[email protected]>",
  "to": ["[email protected]"],
  "subject": "Your verification code is 481920",
  "html": "<div>...</div>",
  "text": "Your code: 481920",
  "received_at": "2026-09-16T09:12:00Z",
  "is_read": false
}

Update message

PATCH/v1/addresses/{address}/messages/{id}

Marks a message as read or unread.

Parameters

isReadrequired boolean New read state.

Request

cURL

curl -X PATCH https://api.example.com/v1/addresses/[email protected]/messages/msg_aurora_0 \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"isRead":true}'

Response

json

{ "id": "msg_aurora_0", "is_read": true }

Delete message

DELETE/v1/addresses/{address}/messages/{id}

Permanently deletes a message from the inbox.

Request

cURL

curl -X DELETE https://api.example.com/v1/addresses/[email protected]/messages/msg_aurora_0 \
  -H "Authorization: Bearer $KEY"

Response

json

{ "ok": true }