Messages

---

List messages

GET /inboxes/:id/messages

Returns all messages received by an inbox.

Query parameters

Param	Type	Description
q	string	Filter by subject (case-insensitive substring match)
from	string	Filter by sender address (case-insensitive substring match)
page	number	Page number (default: 1)
limit	number	Results per page, max 100 (default: 20)
wait	number	Long-poll: block up to N seconds (max 60) until a message arrives

Wait for a message

The ?wait parameter turns the request into a long-poll. The connection stays open until either a message arrives or the timeout is reached. This is the recommended approach for test assertions — no polling loop needed.

# Block up to 30 seconds for the next message
curl "https://api.inboxical.com/v1/inboxes/ix_3f9a/messages?wait=30" \
  -H "X-API-Key: $API_KEY"

// In a test — waits until the email arrives (up to 30s)
const messages = await api.get(`/inboxes/${inbox.id}/messages?wait=30`)
const [msg] = messages
expect(msg.subject).toBe('Welcome to MyApp!')

Response 200

[
  {
    "id": "msg_7b2c",
    "inbox_id": "ix_3f9a",
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Welcome to MyApp!",
    "text": "Thanks for signing up...",
    "html": "<h1>Thanks for signing up...</h1>",
    "size": 1240,
    "attachments": [],
    "received_at": "2026-03-21T12:00:03Z"
  }
]

---

Get a message

GET /inboxes/:id/messages/:messageId

Returns a single message with full body content.

curl https://api.inboxical.com/v1/inboxes/ix_3f9a/messages/msg_7b2c \
  -H "X-API-Key: $API_KEY"

---

Delete a message

DELETE /inboxes/:id/messages/:messageId

curl -X DELETE https://api.inboxical.com/v1/inboxes/ix_3f9a/messages/msg_7b2c \
  -H "X-API-Key: $API_KEY"

Response 204 — no body.

---

Message object

Field	Type	Description
id	string	Unique message ID
inbox_id	string	Parent inbox ID
from	string	Sender address
to	string	Recipient address
subject	string	Email subject
text	string	Plain-text body
html	string	HTML body
size	number	Message size in bytes
attachments	array	List of attachment objects
received_at	string	ISO 8601 timestamp