Authentication
All API requests require authentication using your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEYBase URL: https://api.getinbox.app/v1
Send Message
POST /sendSend a message to one or more recipients. Supports various message types including OTP, delivery notifications, transactions, and events.
Request Body
{
"to": "+15551234567",
"type": "otp",
"body": {
"code": "123456",
"purpose": "signin",
"expires_at": "2025-01-15T10:30:00Z"
}
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| to | string | Yes | Recipient phone number in E.164 format |
| type | string | Yes | Message type: otp, delivery, transaction, event |
| body | object | Yes | Message content (varies by type) |
Response
{
"id": "msg_1234567890",
"status": "sent",
"to": "+15551234567",
"created_at": "2025-01-15T10:25:00Z"
}Bulk Send
POST /send/bulkSend messages to multiple recipients in a single request. Maximum 1000 recipients per request.
Request Body
[
{
"to": "+15551234567",
"type": "otp",
"body": {
"code": "123456",
"purpose": "signin",
"expires_at": "2025-01-15T10:30:00Z"
}
},
{
"to": "+15559876543",
"type": "delivery",
"body": {
"order_id": "A-123",
"status": "shipped",
"tracking_url": "https://fedex.com/track/123456"
}
}
]Response
{
"batch_id": "batch_1234567890",
"total": 2,
"accepted": 2,
"rejected": 0,
"messages": [
{
"id": "msg_1234567890",
"status": "sent",
"to": "+15551234567"
},
{
"id": "msg_1234567891",
"status": "sent",
"to": "+15559876543"
}
]
}Get Message
GET /messages/{id}Retrieve details about a specific message, including delivery status and read receipts.
Response
{
"id": "msg_1234567890",
"to": "+15551234567",
"type": "otp",
"status": "delivered",
"body": {
"code": "123456",
"purpose": "signin",
"expires_at": "2025-01-15T10:30:00Z"
},
"created_at": "2025-01-15T10:25:00Z",
"delivered_at": "2025-01-15T10:25:03Z",
"read_at": "2025-01-15T10:25:15Z"
}List Messages
GET /messagesRetrieve a paginated list of messages with optional filtering.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Number of messages to return (1-100, default: 20) |
| offset | integer | Number of messages to skip (default: 0) |
| type | string | Filter by message type |
| status | string | Filter by status: sent, delivered, read, failed |
Response
{
"messages": [
{
"id": "msg_1234567890",
"to": "+15551234567",
"type": "otp",
"status": "delivered",
"created_at": "2025-01-15T10:25:00Z"
}
],
"total": 1,
"limit": 20,
"offset": 0,
"has_more": false
}Error Codes
| Code | Status | Description |
|---|---|---|
| 400 | Bad Request | Invalid request format or missing required fields |
| 401 | Unauthorized | Invalid or missing API key |
| 403 | Forbidden | Insufficient permissions or rate limit exceeded |
| 404 | Not Found | Message or resource not found |
| 422 | Unprocessable Entity | Invalid phone number or message content |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server error, please try again |
Rate Limits
Default Limits
- • 5,000 messages/month - Free tier
- • 1000 requests/minute - API calls
- • 10 requests/second - Per endpoint
Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset