API Reference: Messages
Complete reference for the Messages API including endpoints, request/response schemas, and examples.
Authentication
All message endpoints require a valid API key passed in the
Authorization header as Bearer <token>.GET
/api/v1/inboxes/{inboxId}/messagesList all messages in an inbox with pagination support.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| inboxId | string | Required | The ID of the inbox to list messages for. |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | integer | Optional | Number of results per page.(default: 20) |
| offset | integer | Optional | Number of results to skip.(default: 0) |
bash
curl -s "https://agentinbox.in/api/v1/inboxes/inb_123/messages?limit=20&offset=0" \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
const messages = await client.messages.list("inb_123", { limit: 20, offset: 0,}); console.log(messages.data[0].subject);python
messages = client.messages.list("inb_123", limit=20, offset=0)print(messages.data[0].subject)Responses
HTTP 200
{ "data": [ { "id": "msg_456", "inboxId": "inb_123", "subject": "Your verification code", "from": "noreply@example.com", "to": ["k3v9x2m4q7tz@agentinbox.in"], "receivedAt": "2024-06-12T10:02:30Z", "read": false } ], "pagination": { "limit": 20, "offset": 0, "total": 3 }}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Inbox not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to list messages"}GET
/api/v1/messages/{id}Retrieve a specific message with full body, headers, and extractions.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique message ID. |
bash
curl -s https://agentinbox.in/api/v1/messages/msg_456 \ -H "Authorization: Bearer $AgentInbox_API_KEY"typescript
const message = await client.messages.get("msg_456");console.log(message.body.text);console.log(message.extractions[0].value);python
message = client.messages.get("msg_456")print(message.body.text)print(message.extractions[0].value)Responses
HTTP 200
{ "id": "msg_456", "inboxId": "inb_123", "subject": "Your verification code", "from": "noreply@example.com", "to": ["k3v9x2m4q7tz@agentinbox.in"], "receivedAt": "2024-06-12T10:02:30Z", "read": true, "headers": { "Content-Type": "text/html; charset=utf-8", "X-Mailer": "ExampleMailer" }, "body": { "text": "Your verification code is 123456. It expires in 10 minutes.", "html": "<html><body>Your verification code is <b>123456</b>...</body></html>", "raw": "..." }, "extractions": [ { "id": "ext_789", "type": "otp", "value": "123456", "confidence": 0.98, "createdAt": "2024-06-12T10:02:31Z" } ]}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Message not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to retrieve message"}POST
/api/v1/messages/{id}/extractExtract structured data (OTP, magic link, etc.) from a message body.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The unique message ID. |
Request Body
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | Required | Extraction type. One of otp, magic_link, password_reset, email, check. |
bash
curl -s -X POST https://agentinbox.in/api/v1/messages/msg_456/extract \ -H "Authorization: Bearer $AgentInbox_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "otp" }'typescript
const extraction = await client.messages.extract("msg_456", { type: "otp",}); console.log(extraction.value); // "123456"python
extraction = client.messages.extract("msg_456", type="otp")print(extraction.value) # "123456"Responses
HTTP 200
{ "id": "ext_789", "type": "otp", "value": "123456", "confidence": 0.98, "createdAt": "2024-06-12T10:02:31Z"}HTTP 400
{ "error": "Invalid request", "message": "Unsupported extraction type"}HTTP 401
{ "error": "Unauthorized", "message": "Invalid or missing API key"}HTTP 404
{ "error": "Not found", "message": "Message not found"}HTTP 500
{ "error": "Internal server error", "message": "Failed to extract data"}Auto-Extraction
When retrieving a message via
GET /api/v1/messages/{id}, extractions are automatically populated if the system detects known patterns (OTP codes, links, etc.). You can also trigger manual extraction with the extract endpoint.Schema: Message
The Message object represents an email received in an inbox.
Message Object
{ "id": string, "inboxId": string, "subject": string, "from": string, "to": string[], "receivedAt": string, // ISO 8601 "read": boolean, "headers": object, "body": { "text": string, "html": string, "raw": string }, "extractions": Extraction[]}