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) |
bash
curl -s "https://agentinbox.in/api/v1/inboxes/00000000-0000-4000-8000-000000000001/messages?limit=20" \ -H "Authorization: Bearer $AGENTINBOX_API_KEY"typescript
const messages = await client.messages.list("00000000-0000-4000-8000-000000000001", 20); console.log(messages.data[0].subject);python
messages = client.inboxes.list_messages("00000000-0000-4000-8000-000000000001")print(messages[0]["subject"])Responses
HTTP 200
{ "object": "list", "data": [ { "id": "msg_456", "inboxId": "inb_123", "subject": "Your verification code", "fromEmail": "noreply@example.com", "toEmail": "k3v9x2m4q7tz@agentinbox.in", "receivedAt": "2024-06-12T10:02:30Z" } ], "nextCursor": null, "hasMore": false}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/00000000-0000-4000-8000-000000000002 \ -H "Authorization: Bearer $AGENTINBOX_API_KEY"typescript
const message = await client.messages.get("00000000-0000-4000-8000-000000000002");console.log(message.textBody);console.log(message.htmlBody);python
message = client.messages.get("00000000-0000-4000-8000-000000000002")print(message.text_body)print(message.html_body)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/00000000-0000-4000-8000-000000000002/extract \ -H "Authorization: Bearer $AGENTINBOX_API_KEY" \ -H "Content-Type: application/json"typescript
const extractions = await client.messages.extract("00000000-0000-4000-8000-000000000002"); console.log(extractions.data[0]?.value); // "123456"python
extractions = client.messages.extract("00000000-0000-4000-8000-000000000002")print(extractions["data"][0]["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[]}