API Documentation

Complete API reference for programmatic access to your Inboxto account

Getting Started

Base URL

https://inboxto.app/api

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: Bearer ib_your_api_key

You can create API keys in your account settings.

Rate Limiting

API requests are limited to 100 requests per hour by default. Rate limit headers are included in all responses.

Interactive API Tester

Enter your API key to start testing

API Endpoints

POST /v1/addresses

Create Email Address

Create a new email address for your account

Required Permissions

addresses:write

Parameters

NameTypeRequiredDescription
addressstringYesThe email address to create
display_namestringNoDisplay name for the address
typestringNoType of address (custom, temporary, etc.)
is_primarybooleanNoSet as primary address

Example Request

curl -X POST https://inboxto.app/api/v1/addresses \
  -H "Authorization: Bearer ib_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "test@example.com",
    "display_name": "Test Address",
    "type": "custom",
    "is_primary": false
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "address": "test@example.com",
    "display_name": "Test Address",
    "type": "custom",
    "is_primary": false,
    "created_at": "2024-01-01T00:00:00Z"
  }
}
GET /v1/addresses

List Email Addresses

Get all email addresses for your account

Required Permissions

addresses:read

Example Request

curl -X GET https://inboxto.app/api/v1/addresses \
  -H "Authorization: Bearer ib_your_api_key"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "address": "test@example.com",
      "display_name": "Test Address",
      "type": "custom",
      "is_primary": false,
      "message_count": 5,
      "unread_count": 2,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
GET /v1/messages

List Messages

Get messages for a specific email address

Required Permissions

messages:read

Parameters

NameTypeRequiredDescription
addressstringYesEmail address to get messages for
limitnumberNoMaximum number of messages to return (default: 20)
offsetnumberNoNumber of messages to skip (default: 0)
unreadbooleanNoFilter unread messages only

Example Request

curl -X GET "https://inboxto.app/api/v1/messages?address=test@example.com&limit=10" \
  -H "Authorization: Bearer ib_your_api_key"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "from": "sender@example.com",
      "to": "test@example.com",
      "subject": "Test Message",
      "text_body": "Hello World",
      "html_body": "<p>Hello World</p>",
      "unread": true,
      "received_at": "2024-01-01T00:00:00Z"
    }
  ]
}
GET /v1/messages/:id

Get Message Details

Get detailed information about a specific message

Required Permissions

messages:read

Parameters

NameTypeRequiredDescription
idstringYesMessage ID

Example Request

curl -X GET https://inboxto.app/api/v1/messages/message-uuid \
  -H "Authorization: Bearer ib_your_api_key"

Example Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "from": "sender@example.com",
    "to": "test@example.com",
    "subject": "Test Message",
    "text_body": "Hello World",
    "html_body": "<p>Hello World</p>",
    "headers": {},
    "attachments": [],
    "unread": true,
    "received_at": "2024-01-01T00:00:00Z"
  }
}
DELETE /v1/messages/:id

Delete Message

Delete a specific message

Required Permissions

messages:delete

Parameters

NameTypeRequiredDescription
idstringYesMessage ID

Example Request

curl -X DELETE https://inboxto.app/api/v1/messages/message-uuid \
  -H "Authorization: Bearer ib_your_api_key"

Example Response

{
  "success": true,
  "message": "Message deleted successfully"
}
POST /v1/messages/pop

Pop Latest Message

Get and delete the latest unread message (queue-like behavior)

Required Permissions

messages:readmessages:delete

Parameters

NameTypeRequiredDescription
addressstringYesEmail address to pop message from

Example Request

curl -X POST https://inboxto.app/api/v1/messages/pop \
  -H "Authorization: Bearer ib_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"address": "test@example.com"}'

Example Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "from": "sender@example.com",
    "to": "test@example.com",
    "subject": "Test Message",
    "text_body": "Hello World",
    "html_body": "<p>Hello World</p>",
    "received_at": "2024-01-01T00:00:00Z"
  },
  "message": "Message popped successfully"
}

Error Responses

401 Unauthorized

{
  "success": false,
  "error": "Invalid API key"
}

403 Forbidden

{
  "success": false,
  "error": "Permission denied"
}

429 Too Many Requests

{
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Maximum 100 requests per hour"
}