API Reference

Everything you need to create inboxes, receive email, and query messages programmatically.

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

Overview

givemeyour.email gives you disposable email inboxes with a REST API. Create an inbox, get an address, send email to it, and poll or webhook for messages — all over HTTP with no SDKs required.

There are two inbox types: anonymous inboxes (no account needed, expire after 24h) and named inboxes (require an org, live as long as you want, great for monitors and testing pipelines).

Authentication

Anonymous inbox reads use the inbox token as a URL path segment — no headers needed. Org-level operations (named inboxes, monitors, billing) require a Bearer token in the Authorization header.

Request header

Authorization: Bearer org_live_abc123...

Get your API key from your org dashboard after creating an account.

Base URL

https://api.givemeyour.email

All endpoints are HTTPS only. HTTP requests are not accepted.

Errors

Errors return standard HTTP status codes with a JSON body:

{
  "error": "inbox_not_found",
  "message": "No inbox found for the given token"
}

Status	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — missing or invalid Bearer token
`403`	Forbidden — token doesn't own this resource
`404`	Not found — inbox or message doesn't exist
`429`	Rate limited — slow down

POST /orgs/:org_id/inboxes

POST /orgs/:org_id/inboxes Create a named inbox

Creates a new named inbox under your org. Named inboxes are persistent and can be queried by API key.

Body parameters

Parameter	Type	Description
`slug`	string optional	Human-readable slug, e.g. `heartbeat-prod`. Auto-generated if omitted.
`ttl_days`	number optional	Auto-expire after N days. Omit for indefinite.

Example request

curl -X POST https://api.givemeyour.email/orgs/org_abc/inboxes \
  -H "Authorization: Bearer org_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"slug": "heartbeat-prod"}'

Response 201

{
  "token": "tk_a3f9d2",
  "address": "heartbeat-prod@givemeyour.email",
  "org_id": "org_abc",
  "created_at": "2026-10-01T17:00:00Z"
}

GET /inbox/:token

GET /inbox/:token List messages

Returns all messages in the inbox, most recent first. No auth header needed — the token is the secret.

Query parameters

Parameter	Type	Description
`limit`	number optional	Max messages to return. Default 20, max 100.
`since`	ISO 8601 optional	Only return messages received after this timestamp.

Example

curl https://api.givemeyour.email/inbox/tk_a3f9d2

Response 200

{
  "messages": [
    {
      "id": "msg_7x9k2",
      "from": "noreply@github.com",
      "subject": "Verify your email",
      "received_at": "2026-10-01T17:42:11Z",
      "has_html": true
    }
  ],
  "count": 1
}

GET /inbox/:token/:message_id

GET /inbox/:token/:message_id Get full message content

Returns the full message including body. Use ?format=html to get the HTML part.

Example

curl https://api.givemeyour.email/inbox/tk_a3f9d2/msg_7x9k2

Response 200

{
  "id": "msg_7x9k2",
  "from": "noreply@github.com",
  "to": "heartbeat-prod@givemeyour.email",
  "subject": "Verify your email",
  "received_at": "2026-10-01T17:42:11Z",
  "body_text": "Click here to verify: https://...",
  "body_html": "<p>Click here to verify...</p>"
}

DELETE /inbox/:token

DEL /inbox/:token Delete inbox and all messages

Permanently deletes the inbox and all its messages. No auth header needed for anonymous inboxes; Bearer token required for named inboxes.

Example

curl -X DELETE https://api.givemeyour.email/inbox/tk_a3f9d2

Response 204

No content

POST /orgs/:org_id/monitors

POST /orgs/:org_id/monitors Create an email delivery monitor

Monitors watch an inbox for expected email and alert you if it doesn't arrive within a window. The classic use case: your app sends a heartbeat email every hour — the monitor pages you if that stops.

💡

This is an external check that lives outside your app. It will fire even if your entire email pipeline is down, unlike an in-app alert that routes through the same broken system.

Body parameters

Parameter	Type	Description
`inbox_token`	string required	The inbox to watch.
`window_minutes`	number required	Alert if no email arrives within this window.
`alert_url`	string required	Webhook URL to POST when the monitor fires.
`subject_match`	string optional	Only count emails whose subject contains this string.
`name`	string optional	Human-readable label shown in alerts.

Example request

curl -X POST https://api.givemeyour.email/orgs/org_abc/monitors \
  -H "Authorization: Bearer org_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "inbox_token": "tk_a3f9d2",
    "window_minutes": 90,
    "alert_url": "https://hooks.slack.com/...",
    "name": "Daily digest watchdog"
  }'

Response 201

{
  "monitor_id": "mon_zz8f1",
  "status": "active",
  "next_check_at": "2026-10-01T18:30:00Z"
}

GET /orgs/:org_id/monitors

GET /orgs/:org_id/monitors List all monitors

Example

curl https://api.givemeyour.email/orgs/org_abc/monitors \
  -H "Authorization: Bearer org_live_abc123"

DELETE /orgs/:org_id/monitors/:monitor_id

DEL /orgs/:org_id/monitors/:monitor_id Delete a monitor

Example

curl -X DELETE https://api.givemeyour.email/orgs/org_abc/monitors/mon_zz8f1 \
  -H "Authorization: Bearer org_live_abc123"

Response 204

No content

POST /orgs

POST /orgs Create an organization

Creates a new org and returns your API key. This is the first step to using named inboxes and monitors.

Example

curl -X POST https://api.givemeyour.email/orgs \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourcompany.com"}'

Response 201

{
  "org_id": "org_abc",
  "api_key": "org_live_abc123..."
}

⚠️

Save your API key. It is shown once and cannot be retrieved again.

POST /orgs/:org_id/checkout

POST /orgs/:org_id/checkout Start a Stripe checkout session

Returns a Stripe Checkout URL. Redirect your user there to subscribe to a paid plan.

Body parameters

{
  "price_id": "price_pro_monthly",
  "success_url": "https://yourapp.com/settings?upgraded=1",
  "cancel_url": "https://yourapp.com/settings"
}