Account & Billing API

Get account details

GET /account

Retrieve the authenticated user’s account information, plan details, usage counters, and credit balance.

curl https://api.oneshotemail.com/v1/account \
  -H "Authorization: Bearer osm_live_your_key"

Response: 200 OK

{
  "user_id": "usr_a1b2c3d4e5f6",
  "email": "developer@example.com",
  "plan": "solo",
  "usage": {
    "receive": { "used": 142, "limit": 10000 },
    "send": { "used": 23, "limit": 1000 }
  },
  "credits_remaining": 450,
  "billing_cycle_ends": "2026-04-07T00:00:00Z"
}

Response fields:

Field	Type	Description
user_id	string	Your unique account identifier.
email	string	Your account email address.
plan	string	Current plan: free, solo, team, enterprise, max.
usage.receive.used	int	Receive addresses created this billing period.
usage.receive.limit	int	Monthly receive allocation for your plan.
usage.send.used	int	Send addresses created this billing period.
usage.send.limit	int	Monthly send allocation for your plan.
credits_remaining	int	Available credits for overage use.
billing_cycle_ends	string	ISO 8601 timestamp when the current billing cycle resets.

---

Purchase credits

POST /account/credits

Initiate a credit purchase via Stripe Checkout. Returns a URL that the user should be redirected to (or opened in a browser) to complete payment.

curl -X POST https://api.oneshotemail.com/v1/account/credits \
  -H "Authorization: Bearer osm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500}'

Request body:

Field	Type	Required	Description
amount	int	Yes	Number of credits to purchase.

Available packs: 100, 500, 2000. If the requested amount does not match a pack size, the API selects the closest pack that covers the requested amount.

Response: 200 OK

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3..."
}

Open the checkout_url in a browser to complete the purchase. After successful payment, credits are added to your account automatically via Stripe webhook.

Error responses

Status	Code	Description
400	VALIDATION_ERROR	Invalid amount.
401	UNAUTHORIZED	Missing or invalid API key.
403	FORBIDDEN	Account not yet approved (free tier queue).

---

Register (free tier)

POST /account/register

Register a new account and join the free tier queue. Accounts may be auto-approved (for .edu emails and known company domains) or placed in a queue.

curl -X POST https://api.oneshotemail.com/v1/account/register \
  -H "Content-Type: application/json" \
  -d '{"email": "developer@example.com"}'

Request body:

Field	Type	Required	Description
email	string	Yes	Your email address.

Response: 202 Accepted (queued)

{
  "status": "queued",
  "queue_position": 47,
  "message": "You're on the list! We'll email you when your account is ready."
}

Response: 201 Created (auto-approved)

{
  "api_key": "osm_live_aBcDeFgHiJkLmNoPqRsT...",
  "message": "You're in! Save this API key -- you won't see it again."
}

The API key is shown once. If you lose it, you will need to regenerate it from account settings.

Auto-approval criteria

Accounts are automatically approved (skip the queue) when:

• The email domain is .edu (educational institution).
• The email domain is on the configured company domain allowlist.
• The account was referred by an existing paid user.

---

Health check

GET /health

Check the API health status. This endpoint does not require authentication.

curl https://api.oneshotemail.com/v1/health

Response: 200 OK

{
  "status": "ok",
  "region": "ap-southeast-2",
  "version": "1.2.3"
}

Response fields:

Field	Type	Description
status	string	"ok" when the service is healthy.
region	string	AWS region serving this request.
version	string	Current API version deployed.

Use this endpoint for:

• Monitoring and uptime checks.
• Verifying connectivity before running a test suite.
• Confirming the API is reachable from your CI/CD environment.