API Reference

Base URL: https://api.useblip.email

All endpoints accept and return JSON. Include Content-Type: application/json for POST requests.

Authentication

Requests are authenticated via Bearer token in the Authorization header:

Authorization: Bearer {token}

Two token types are supported:

Session token — Created via POST /v1/sessions. Free tier, expires in 24 hours.
API key — Created via POST /v1/api-keys. Requires AGENT subscription. Prefixed with blip_ak_. Does not expire.

Sessions

POST /v1/sessions

Create an anonymous session. No auth required.

Response:

{"token": "...", "session": {"id": "...", "tier": "FREE", "expiresAt": "..."}}

GET /v1/sessions/me

Get current session info. Requires auth.

Inboxes

POST /v1/inboxes

Create a new inbox.

Request body (all fields optional):

{

"slug": "my-custom-name", // PRO/AGENT only

"domain": "bl1p.dev", // default: first active domain

"windowMinutes": 60 // custom TTL (AGENT) or sniper window (PRO)

}

GET /v1/inboxes

List all inboxes for the current session/user.

GET /v1/inboxes/{id}

Get inbox details including email list.

DELETE /v1/inboxes/{id}

Delete an inbox and all its emails.

Emails

GET /v1/emails/{id}

Get full email content including body and attachments.

Response:

{"id": "...", "from": "...", "to": "...", "subject": "...",

"textBody": "...", "htmlBody": "...", "receivedAt": "...",

"attachments": [{"name": "...", "size": 1024, "contentType": "..."}]}

GET /v1/emails/{id}/extract

Extract OTP codes and verification links from a specific email.

GET /v1/inboxes/{id}/extract

Extract OTP/links from the most recent email in an inbox. Ideal for agents.

Response:

{"otps": ["847293"], "links": ["https://example.com/verify?token=xyz"]}

GET /v1/emails/{id}/attachments/{name} PRO

Download an email attachment.

POST /v1/emails/{id}/reply PRO

Reply to an email. 10 replies/day.

{"body": "Thanks for the info!"}

Real-time (SSE)

GET /v1/inboxes/{id}/sse

Server-Sent Events stream. Emits an event for each new email.

event: connected

data: {}

event: email

data: {"id": "...", "from": "...", "subject": "..."}

Auth via header or query: ?token={bearer_token}

Webhooks

POST /v1/webhooks PRO AGENT

Create a webhook.

{"url": "https://your-server.com/hook", "inboxId": "..."}

GET /v1/webhooks

List all webhooks.

PATCH /v1/webhooks/{id}

Enable or disable a webhook. Body: {"enabled": true}

DELETE /v1/webhooks/{id}

Delete a webhook.

GET /v1/webhooks/{id}/deliveries

View delivery log (last 50 attempts).

See the Webhooks guide for payload format and signature verification.

Forwarding

POST /v1/inboxes/{id}/forwarding PRO

Create forwarding rule.

{"forwardToEmail": "me@example.com"}

GET /v1/inboxes/{id}/forwarding

List forwarding rules for an inbox.

DELETE /v1/forwarding/{id}

Delete a forwarding rule.

API Keys

POST /v1/api-keys AGENT

Create an API key. Body: {"name": "..."}

GET /v1/api-keys

List API keys (prefix only, not the full key).

DELETE /v1/api-keys/{id}

Revoke an API key.

Rate Limits

Category	Limit	Scoped by
Public (sessions, auth)	30/min	IP
Authenticated reads	120/min	Token
Writes	20/min	Token

Errors

All errors return JSON:

{"error": "bad_request", "message": "Unsupported domain: example.com"}

Status	Meaning
400	Bad request / validation error
401	Missing or invalid auth token
402	Tier limit exceeded
403	Access denied
404	Not found
500	Internal server error