API reference

operationId: getHealth

No authentication. Confirms the Worker is up.

GET https://api.inboxrhino.in/health

{"status":"ok","service":"inboxrhino-api"}

operationId: createInbox

Creates a receive-only address on test.inboxrhino.in and the matching Cloudflare Email Routing rule. Body may be omitted or empty. The only allowed JSON field is prefix.

Success is 201. Omit prefix to receive a generated local-part such as bright-otter-ab12.

curl --request POST https://api.inboxrhino.in/v1/inboxes \
  --header "Authorization: Bearer $INBOXRHINO_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: signup-test-1" \
  --data '{"prefix":"signup-test"}'

{
  "data": {
    "id": "inbox_0123456789abcdef0123456789abcdef",
    "address": "signup-test@test.inboxrhino.in",
    "local_part": "signup-test",
    "status": "active",
    "created_at": "2026-09-03T10:15:30.000Z"
  }
}

operationId: listInboxes

Lists active inboxes for the organisation. Newest first.

operationId: getInbox

Returns one active inbox. Unknown, deleted, or foreign ids return 404 inbox_not_found.

operationId: deleteInbox

Removes the Email Routing rule, deletes retained messages and stored objects, and frees an active-inbox slot. Success is 204 with an empty body. Monthly email quota is not restored.

curl --request DELETE https://api.inboxrhino.in/v1/inboxes/INBOX_ID \
  --header "Authorization: Bearer $INBOXRHINO_API_KEY"

operationId: listOrWaitForMessages

Lists retained messages for one inbox, or waits until a match arrives. There is no organisation-wide list. Filters combine with AND. Without include=content, each item is a summary (no text, html, headers, or attachments).

{
  "data": [
    {
      "id": "msg_0123456789abcdef0123456789abcdef",
      "inbox_id": "inbox_0123456789abcdef0123456789abcdef",
      "from": { "name": "Acme", "address": "noreply@example.com" },
      "to": "signup-test@test.inboxrhino.in",
      "subject": "Verify your email",
      "preview": "Use this code to verify your address.",
      "size_bytes": 4096,
      "received_at": "2026-09-03T10:16:02.000Z",
      "expires_at": "2026-10-03T10:16:02.000Z",
      "internet_message_id": "<abc@example.com>",
      "text": "Your code is 482193",
      "html": "<p>Your code is 482193</p>",
      "headers": [["Subject", "Verify your email"], ["From", "Acme <noreply@example.com>"]],
      "attachments": [
        {
          "id": "att_0123456789abcdef0123456789abcdef",
          "filename": "invoice.pdf",
          "content_type": "application/pdf",
          "size_bytes": 20480,
          "disposition": "attachment",
          "content_id": null,
          "download_url": "https://files.inboxrhino.in/v1/attachments/att_0123456789abcdef0123456789abcdef"
        }
      ]
    }
  ],
  "next_cursor": null
}

operationId: getMessage

Returns the complete parsed message: summary fields plus internet_message_id, text, html, headers (array of [name, value] pairs), and attachments. Always includes content; no include query is needed.

curl --request GET https://api.inboxrhino.in/v1/messages/MESSAGE_ID \
  --header "Authorization: Bearer $INBOXRHINO_API_KEY"

operationId: deleteMessage

Deletes the message and stored objects. Success is 204. Does not restore monthly email quota. Prefer deleting the inbox at the end of a test unless you must keep the address.

operationId: downloadAttachment

Downloads raw bytes. Use the download_url from the message, which points at https://files.inboxrhino.in. The same path on https://api.inboxrhino.in is implemented by the same Worker. Auth is still the API Bearer key. Response is not JSON: Content-Disposition is attachment, Content-Type is the stored MIME type, Cache-Control is private, no-store. Content is not malware-scanned.

curl --request GET https://files.inboxrhino.in/v1/attachments/ATTACHMENT_ID \
  --header "Authorization: Bearer $INBOXRHINO_API_KEY" \
  --output invoice.pdf

operationId: getUsage

Current free-tier plan, UTC month window, active inbox count, and emails received this period. No data wrapper. plan is currently always free.

{
  "plan": "free",
  "period": { "starts_at": "2026-09-01T00:00:00.000Z", "ends_at": "2026-10-01T00:00:00.000Z" },
  "inboxes": { "active": 4, "limit": 11, "remaining": 7 },
  "emails": { "received": 21, "limit": 33, "remaining": 12 }
}