Messages - Inkbox

Messages represent individual emails in a mailbox. List and detail endpoints return message metadata; full body content (text/HTML) is fetched from storage on detail requests. All list endpoints use cursor-based pagination. POST /messages sends immediately. To save incomplete content, autosave changes, or review attachments before sending, use Drafts. Drafts do not appear in message, thread, or search results until sent.

List messages

GET /mailboxes/{email_address}/messages

List messages in a mailbox, newest first, with cursor pagination.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Opaque cursor from a previous response’s `next_cursor`
`limit`	integer	50	Results per page (1–100)
`direction`	string	—	Filter by `"inbound"` or `"outbound"`. Omit for all messages
`start_datetime`	string	—	Only messages created on or after this date/time
`end_datetime`	string	—	Only messages created on or before this date/time; a bare date includes the whole day
`tz`	string	UTC	IANA zone for interpreting zone-less `start_datetime`/`end_datetime` values. Defaults to UTC

start_datetime, end_datetime, and tz filter on created_at. Both bounds are optional and non-breaking — omit them for unchanged behavior. See Filtering by date.

Response (200)

JSON

{
  "items": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "mailbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "thread_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "message_id": "<20250301120000.abc123@inkboxmail.com>",
      "from_address": "agent-sales@inkboxmail.com",
      "to_addresses": ["customer@example.com"],
      "cc_addresses": null,
      "subject": "Your order is confirmed",
      "snippet": "Hi! Your order #1234 has been confirmed and will ship within...",
      "direction": "outbound",
      "status": "sent",
      "is_read": true,
      "is_starred": false,
      "has_attachments": false,
      "reply_to": null,
      "first_opened_at": null,
      "open_count": 0,
      "import_job_id": null,
      "created_at": "2025-03-01T12:00:00Z"
    }
  ],
  "next_cursor": "eyJ0cyI6ICIyMDI1LTAzLTAxVDEyOjAwOjAwWiIsICJpZCI6ICJjM2Q0ZTVmNiJ9",
  "has_more": true
}

Code examples

curl -X GET "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages?limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

const mailboxId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/messages?limit=25`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const page = await response.json();
// page.next_cursor contains the cursor for the next page

import requests

mailbox_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"limit": 25},
)
page = response.json()
# page["next_cursor"] contains the cursor for the next page

Get message

GET /mailboxes/{email_address}/messages/{message_id}

Get a single message with its full body content (plain text and HTML). The body returned is the body Inkbox stored, which is not always the body the caller submitted: outbound body_text/body_html include any automatically applied custom signature and, while it applies, the “Sent via Inkbox” footer — see Branding footer under Send message.

Fetching marks inbound mail read. A GET here with an API key marks an unread inbound message read — is_read comes back true in the same response. Human (Console) reads don’t, and neither do the list, thread, or attachment routes, so an agent that only reads through those still needs the flags PATCH to mark read. This is distinct from first_opened_at, which reflects the recipient opening a message you sent (see Open tracking).

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`message_id`	UUID	Unique identifier of the message

Response (200)

JSON

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "mailbox_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "thread_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "message_id": "<20250301120000.abc123@inkboxmail.com>",
  "from_address": "agent-sales@inkboxmail.com",
  "to_addresses": ["customer@example.com"],
  "cc_addresses": null,
  "bcc_addresses": null,
  "subject": "Your order is confirmed",
  "snippet": "Hi! Your order #1234 has been confirmed and will ship within...",
  "direction": "outbound",
  "status": "sent",
  "is_read": true,
  "is_starred": false,
  "has_attachments": false,
  "reply_to": null,
  "first_opened_at": null,
  "open_count": 0,
  "import_job_id": null,
  "body_text": "Hi! Your order #1234 has been confirmed and will ship within 2 business days.",
  "body_html": "<p>Hi! Your order #1234 has been confirmed and will ship within 2 business days.</p>",
  "in_reply_to": null,
  "references": null,
  "attachment_metadata": null,
  "ses_message_id": "0102018abc123def-abcdef01-2345-6789-abcd-ef0123456789-000000",
  "created_at": "2025-03-01T12:00:00Z",
  "updated_at": "2025-03-01T12:00:00Z"
}

Code examples

curl -X GET "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages/MESSAGE_ID" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/messages/${messageId}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const message = await response.json();

import requests

response = requests.get(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/messages/{message_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
message = response.json()

Send message

POST /mailboxes/{email_address}/messages

Compose and send an email from a mailbox. Threading is automatically resolved from in_reply_to_message_id.

Storage limitsEvery inbox has a storage cap set by your plan. A send that would push the inbox above its cap is refused with a 402 — from this endpoint, reply-all, and forward alike — until space is freed (delete messages or threads) or the plan is upgraded. See pricing for per-plan caps.Receiving is never blocked. Inbound mail is always accepted, and still counts toward the inbox’s usage. Current usage and the cap are on the mailbox object as storage_used_bytes and storage_limit_bytes.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the sending mailbox

Request body

Field	Type	Required	Description
`recipients.to`	string[]	No	Primary recipients
`recipients.cc`	string[]	No	CC recipients
`recipients.bcc`	string[]	No	BCC recipients (excluded from headers, delivered separately)
`subject`	string	Yes	Email subject line (max 998 chars)
`body_text`	string	No	Plain-text body
`body_html`	string	No	HTML body
`in_reply_to_message_id`	string	No	RFC 5322 Message-ID of the email being replied to
`reply_to`	string	No	Optional `Reply-To` address. If set, recipients’ mail clients route replies here instead of the sending mailbox.
`attachments`	object[]	No	File attachments (see below). Decoded attachments may total at most 25 MiB; the complete encoded message must also fit within 10 MiB.
`track_opens`	boolean	No	Embed an open-tracking pixel in the HTML body. Requires `body_html` — a plain-text-only send with `track_opens` returns `422`. Default `false`. See Open tracking.

Provide at least one address across recipients.to, recipients.cc, and recipients.bcc. A message can have at most 50 distinct recipients across these lists; repeated addresses count once, ignoring case. The complete MIME message, including headers, body, attachments, and encoding overhead, must not exceed 10 MiB (10,485,760 bytes). Base64 encoding increases attachment size, so an attachment below the 25 MiB decoded-attachment cap can still exceed the message limit. AttachmentUpload object:

Field	Type	Description
`filename`	string	File name (max 255 chars)
`content_type`	string	MIME type (e.g. `application/pdf`)
`content_base64`	string	Base64-encoded file content
`content_id`	string \| null	Optional content ID (max 255 chars). Reference it in `body_html` as `cid:chart1` when the value is `chart1` to display the attachment inline. Omit it for a regular attachment.

Request example

JSON

{
  "recipients": {
    "to": ["customer@example.com"],
    "cc": null,
    "bcc": null
  },
  "subject": "Your order is confirmed",
  "body_text": "Hi! Your order #1234 has been confirmed.",
  "body_html": "<p>Hi! Your order #1234 has been confirmed.</p>",
  "in_reply_to_message_id": null
}

Response (201)

Returns the created message metadata (same as a list item — body content is not included).

Custom signatures

When enabled and available for the sending mailbox, a custom signature is added to sends, replies, reply-all, and forwards. Configure it through Update mailbox, not in each message request. The stored message includes the applied signature. An HTML signature adds a formatted HTML version to a text-only message while retaining the plain-text fallback. This does not enable open tracking. A text-only signature does not create an HTML version; an existing HTML body keeps its formatting. Original messages forwarded as attachments are unchanged. If the Inkbox branding footer also applies, it appears after the custom signature.

Idempotency

Send, reply-all, and forward accept an optional Idempotency-Key header of up to 255 characters. Omit it and every call is an independent send. Supply it and the key is bound to the email before it is handed off for delivery, so retrying after a lost or timed-out response cannot put a second copy of the email on the wire. This is at-most-once protection, not a replay. A repeat under a key that already sent returns an error rather than the original 201:

Situation	Response
First call	`201` with the created message
Same key, the email was already accepted for delivery	`409`
Same key, an earlier attempt’s outcome is unresolved	`503`, with `detail.error` set to `send_outcome_ambiguous`

A 409 means the email went out. Fetch it with GET /messages?direction=outbound. A 503 means Inkbox cannot confirm what happened to the earlier attempt, so it will not send again under that key; check your outbound messages to see whether one exists. A 503 keeps returning while the outcome stays unresolved, which is deliberate — resolve it by looking the message up, not by forcing a send.

Keys are scoped to your organization and to the endpoint. One key used for a send and for a forward does not collide.
A retry does not spend quota twice. It reuses the original attempt’s recipient allowance rather than consuming it again.
A key is remembered for 7 days, after which it can be used again.
The request body is not part of the key. Reusing a key with different content is refused as an already-accepted send, not delivered. Use a fresh key for each distinct email.
Retry with the same key. Never mint a new one for the same email. A new key is a new send, so if the first attempt did reach delivery, retrying under a fresh key is what puts the second copy on the wire. Errors raised before the send is accepted — validation, policy, storage and rate limits — leave the key unused, so retrying with it behaves like a first attempt.

For send-then-confirm with a response you can safely replay, use drafts instead: create the draft with Idempotency-Key, then send it. A lost response there can be retried and returns the original message. By default, outbound mail carries a short “Sent via Inkbox” footer, appended to the text and HTML parts of every send, reply-all, and forward. Organizations on a paid plan can remove it — see Branding footer. While it applies, the footer is written into the stored message, so it changes what the API gives back: a later GET /messages/{message_id} returns body_text and body_html with the footer appended — not the exact bytes you submitted. A send with no body at all comes back with a body containing only the footer. Snippets and search text are computed from the body you submitted, so snippet and search are unaffected.

Open tracking

Set track_opens on a send or forward to embed an invisible tracking pixel in the HTML body. When the recipient’s mail client loads it, the message reports two fields (present on every message response):

Field	Type	Description
`first_opened_at`	string \| null	ISO 8601 time of the first observed open, or `null` if none seen yet. This is the reliable signal.
`open_count`	integer	Approximate observed opens (default `0`). Automatic image fetching can increase the count, and multiple opens may be counted once.

track_opens requires an HTML part — a plain-text-only send returns 422. Tracking is per-message (“at least one observed open”), not per-recipient, and the pixel can raise spam scores, so a borderline message may be more likely to be filtered. first_opened_at (the recipient loaded the pixel) is distinct from is_read (your agent consumed the message via the API — see Get message).

Error responses

Status	Description
400	Invalid attachment data, an attachment or message size limit was exceeded, or the request was rejected for policy reasons
402	Sending the message would exceed the inbox storage limit — delete messages or upgrade the plan
403	Organization mismatch, recipient restriction, conversation-health restriction, plan requirement, or a request that cannot fit within its effective limit
409	This `Idempotency-Key` already sent an email — see Idempotency
422	Invalid request fields, including an empty recipient set or more than 50 distinct recipients
429	A temporary organization send or new-recipient limit was reached. Retry timing is included when waiting can resolve it
503	An earlier attempt with this `Idempotency-Key` has an unresolved outcome, so no further send was attempted — see Idempotency

Mail limits are shared by every mailbox in the organization and count distinct envelope recipients, not messages. The default fixed-window ceilings are 50 recipients per 10 minutes, 80 per hour, and 100 per 24 hours; plan limits may be higher. An address repeated across To, Cc, or Bcc counts once. A retryable limit response uses structured detail:

{
  "detail": {
    "error": "mail_rate_limited",
    "message": "Sending limit reached: 80 recipients per hour for this organization.",
    "limit": 80,
    "window_seconds": 3600,
    "retry_after_seconds": 120
  }
}

If one request itself exceeds the effective ceiling, waiting cannot help. The API returns 403 with detail.error set to mail_rate_limit_exceeded, along with limit, window_seconds, and recipient_count, and omits Retry-After. Other send controls use distinct detail.error values:

Error	Status	What to do
`conversation_unhealthy`	403	Do not retry unchanged. Follow the response’s recipient-specific guidance before sending again.
`new_external_recipient_limit`	429 or 403	If `Retry-After` is present, wait that many seconds. Without it, reduce the request or change plans before retrying.
`custom_domain_sending_requires_paid_plan`	403	Use a platform-domain mailbox or change plans before retrying.
`unclaimed_agent_recipient_not_allowed`	403	An unclaimed agent may only email its own human. `detail.message` names that address; claim the agent to send anywhere else.
`unclaimed_agent_signup_missing`	403	Verify the agent or resend verification to restore restricted sending.

Use the error code rather than the status alone to choose remediation. A 429 with Retry-After is retryable after the stated delay; a 403 requires a change to the request, recipient relationship, sending mailbox, or plan.

Code examples

curl -X POST "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": {"to": ["customer@example.com"]},
    "subject": "Your order is confirmed",
    "body_text": "Hi! Your order has been confirmed.",
    "body_html": "<p>Hi! Your order has been confirmed.</p>"
  }'

const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/messages`,
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          recipients: { to: ["customer@example.com"] },
          subject: "Your order is confirmed",
          body_text: "Hi! Your order has been confirmed.",
          body_html: "<p>Hi! Your order has been confirmed.</p>",
      }),
  }
);
const message = await response.json();

import requests

response = requests.post(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/messages",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "recipients": {"to": ["customer@example.com"]},
        "subject": "Your order is confirmed",
        "body_text": "Hi! Your order has been confirmed.",
        "body_html": "<p>Hi! Your order has been confirmed.</p>",
    },
)
message = response.json()

Reply to everyone

POST /mailboxes/{email_address}/messages/{message_id}/reply-all

Reply to every visible participant on a stored message. Recipients are resolved server-side from the original — you don’t pass them. The reply stays in the original thread and counts against the same send rate limits as POST /messages.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the replying mailbox
`message_id`	UUID	UUID of the message being replied to

Request body

Field	Type	Required	Description
`subject`	string	No	Override; defaults to `"Re: " + original.subject` (idempotent — won’t double-prefix). Max 998 chars.
`body_text`	string	No	Plain-text reply body.
`body_html`	string	No	HTML reply body.
`attachments`	object[]	No	Base64-encoded attachments. Same `AttachmentUpload` shape and limits as Send.
`reply_to`	string	No	Optional `Reply-To` header on the reply.

Recipient resolution

Inbound original — To is the original Reply-To if present, otherwise the original sender. Cc is the original To + Cc.
Outbound original — To and Cc reuse the original To and Cc.
In both cases the replying mailbox, duplicates, and the original BCC recipients are removed.

The message detail (GET .../messages/{message_id}) returns the resolved reply_all_recipients ({ to, cc }) so UIs can prefill editable fields.

Request example

JSON

{
  "body_text": "Thanks everyone — looping you all back in."
}

Response (201)

Returns a MessageResponse — the brand-new message representing the reply (same shape as a list item; body content is not included). Accepts an optional Idempotency-Key header, under its own key namespace — see Idempotency.

Error responses

Status	Description
400	Attachment blocked/oversize
402	Sending the message would exceed the inbox storage limit — delete messages or upgrade the plan
403	Organization mismatch, contact-rule block, or unclaimed-agent recipient restriction
404	Mailbox or original message not found
409	This `Idempotency-Key` already sent an email — see Idempotency
422	No reply-all recipients could be resolved, or the message was rejected at send time
429	Send rate limit exceeded (same quota as `POST /messages`)
503	An earlier attempt with this `Idempotency-Key` has an unresolved outcome, so no further send was attempted — see Idempotency

Code examples

curl -X POST "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages/MESSAGE_ID/reply-all" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body_text": "Thanks everyone — looping you all back in."
  }'

const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/messages/${messageId}/reply-all`,
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          body_text: "Thanks everyone — looping you all back in.",
      }),
  }
);
const reply = await response.json();

import requests

response = requests.post(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/messages/{message_id}/reply-all",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body_text": "Thanks everyone — looping you all back in.",
    },
)
reply = response.json()

Forward message

POST /mailboxes/{email_address}/messages/{message_id}/forward

Forward a stored message from this mailbox. Each forward creates a new thread. Forwards count against the same send rate limits as POST /messages and fire a message.forwarded webhook event on success (not message.sent).

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the forwarding mailbox
`message_id`	UUID	UUID of the original message to forward

Request body

Field	Type	Required	Description
`recipients.to`	string[]	—	Primary recipients
`recipients.cc`	string[]	—	CC recipients
`recipients.bcc`	string[]	—	BCC recipients (excluded from headers, delivered separately)
`mode`	string	No	`"inline"` (default) or `"wrapped"`. See Modes below.
`subject`	string	No	Override; defaults to `"Fwd: " + original.subject` (idempotent — won’t double-prefix if the original already starts with `Fwd:` / `Fw:`). An empty or missing original subject becomes `"Fwd: (no subject)"`. Max 998 chars.
`body_text`	string	No	Plain-text caller note prepended above the original body (inline) or included as a top-level note (wrapped).
`body_html`	string	No	HTML caller note.
`additional_attachments`	object[]	No	Additional attachments. Same `AttachmentUpload` shape and 25 MiB decoded-attachment cap as Send; the complete encoded forward must also fit within 10 MiB.
`include_original_attachments`	boolean	No	`inline` mode only. Default `true` — original attachments are re-attached as direct outbound parts. Ignored in `wrapped` mode (originals live inside the wrapped `.eml`).
`reply_to`	string	No	Optional `Reply-To` header on the forward’s outer envelope. The original’s `Reply-To` (if any) is preserved inside the wrapped MIME but is not auto-inherited.
`track_opens`	boolean	No	Embed an open-tracking pixel; requires an HTML part on the outgoing forward. Inline mode inherits the original’s HTML; wrapped mode needs a `body_html`. A no-HTML forward returns `422`. Default `false`. See Open tracking.

At least one address is required across recipients.to, recipients.cc, and recipients.bcc. The combined limit is 50 distinct recipients, ignoring case.

Modes

inline (default): Renders the original body below a preamble containing its From:, Date:, Subject:, To:, and Cc: headers. Original attachments appear as direct attachments to the forward. Inline cid: images may break, and complex multipart structure is flattened.
wrapped: Attaches the original message as a single message/rfc822 part, preserving its headers, body parts, attachments, and nested structure. Recipients may see it inline or as a forwarded.eml attachment, depending on their mail client. Use this for originals with inline images, calendar invites, or complex multipart content. The result preserves the message’s meaning and structure but may change its byte representation. DKIM-preserving forwarding is not supported.

Forwarding behaviour

Original-attachment bytes are excluded from the 25 MiB cap on additional attachments. The complete MIME message, including the original content and encoding overhead, must fit within 10 MiB.
The forward gets a brand-new Message-ID. The original is referenced via an X-Forwarded-Message-Id header.
Filename collisions across original attachments and caller additional_attachments are deduplicated automatically (caller wins; originals get a forwarded- prefix and a numeric suffix).

Request example

JSON

{
  "recipients": {"to": ["partner@example.com"]},
  "mode": "inline",
  "body_text": "Heads up — see below.",
  "include_original_attachments": true
}

Response (201)

Returns a MessageResponse — the brand-new message representing the forward (same shape as a list item; body content is not included). Accepts an optional Idempotency-Key header, under its own key namespace — see Idempotency.

Error responses

Status	Description
400	Invalid attachment data, a size limit was exceeded, or the request was rejected for policy reasons
402	Sending the message would exceed the inbox storage limit — delete messages or upgrade the plan
403	Organization mismatch, contact-rule block, or unclaimed-agent recipient restriction
404	Mailbox or original message not found
409	This `Idempotency-Key` already sent an email — see Idempotency
422	Original message cannot be forwarded
429	Send rate limit exceeded (same quota as `POST /messages`)
502	Failed to load original body or attachments from storage
503	An earlier attempt with this `Idempotency-Key` has an unresolved outcome, so no further send was attempted — see Idempotency

Code examples

curl -X POST "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages/MESSAGE_ID/forward" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": {"to": ["partner@example.com"]},
    "mode": "inline",
    "body_text": "Heads up — see below."
  }'

const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/messages/${messageId}/forward`,
  {
      method: "POST",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({
          recipients: { to: ["partner@example.com"] },
          mode: "inline",
          body_text: "Heads up — see below.",
      }),
  }
);
const forwarded = await response.json();

import requests

response = requests.post(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/messages/{message_id}/forward",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "recipients": {"to": ["partner@example.com"]},
        "mode": "inline",
        "body_text": "Heads up — see below.",
    },
)
forwarded = response.json()

Update message flags

PATCH /mailboxes/{email_address}/messages/{message_id}

Update is_read or is_starred on a message. Omit a field to leave it unchanged. This is how to mark mail read in bulk, to mark a message unread, or to mark read when you process from the list or thread routes (which never mark read on their own). Fetching a single inbound message with an API key marks it read automatically — see Get message.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`message_id`	UUID	Unique identifier of the message

Request body

Field	Type	Required	Description
`is_read`	boolean	No	Mark as read (`true`) or unread (`false`)
`is_starred`	boolean	No	Star or unstar the message

Code examples

curl -X PATCH "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages/MESSAGE_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"is_read": true}'

const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/messages/${messageId}`,
  {
      method: "PATCH",
      headers: {
          "X-API-Key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      body: JSON.stringify({ is_read: true }),
  }
);
const updated = await response.json();

import requests

response = requests.patch(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/messages/{message_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_read": True},
)
updated = response.json()

Delete message

DELETE /mailboxes/{email_address}/messages/{message_id}

Delete a message. Returns 204 No Content on success. Deleting a message frees its storage immediately — the message and its associated storage overhead stop counting toward the inbox’s storage cap right away.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`message_id`	UUID	Unique identifier of the message

Code examples

curl -X DELETE "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages/MESSAGE_ID" \
  -H "X-API-Key: YOUR_API_KEY"

await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/messages/${messageId}`,
  {
      method: "DELETE",
      headers: { "X-API-Key": "YOUR_API_KEY" },
  }
);

import requests

requests.delete(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/messages/{message_id}",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

Download attachment

GET /mailboxes/{email_address}/messages/{message_id}/attachments/{filename}

Download an attachment from a message. By default, responds with a 302 redirect to a temporary download URL. Set redirect=false to get the URL as JSON instead.

Path parameters

Parameter	Type	Description
`email_address`	string	Email address of the mailbox
`message_id`	UUID	Unique identifier of the message
`filename`	string	Attachment filename (must match exactly with `attachment_metadata[].filename`)

Query parameters

Parameter	Type	Default	Description
`redirect`	boolean	`true`	`true` returns a `302` redirect to the download URL. `false` returns the URL as JSON.

Response (302) — redirect mode (default)

Redirects to a temporary download URL with a Content-Disposition: attachment header. The URL is valid for 15 minutes.

Response (200) — JSON mode

JSON

{
  "url": "https://downloads.example.com/messages/abc123/document.pdf?...",
  "filename": "document.pdf",
  "expires_in": 900
}

Field	Type	Description
`url`	string	Temporary download URL (valid for 15 minutes)
`filename`	string	Attachment filename
`expires_in`	integer	URL expiration time in seconds

Error responses

Status	Description
403	Mailbox does not belong to your organization
404	Mailbox, message, or attachment not found

Code examples

# Redirect mode (default) — follows redirect to download
curl -L "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages/MESSAGE_ID/attachments/document.pdf" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o document.pdf

# JSON mode — get the URL without redirecting
curl "https://inkbox.ai/api/v1/mail/mailboxes/EMAIL_ADDRESS/messages/MESSAGE_ID/attachments/document.pdf?redirect=false" \
  -H "X-API-Key: YOUR_API_KEY"

// JSON mode — get a temporary download URL
const response = await fetch(
  `https://inkbox.ai/api/v1/mail/mailboxes/${emailAddress}/messages/${messageId}/attachments/document.pdf?redirect=false`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { url, filename, expires_in } = await response.json();

import requests

# JSON mode
response = requests.get(
    f"https://inkbox.ai/api/v1/mail/mailboxes/{email_address}/messages/{message_id}/attachments/document.pdf",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"redirect": "false"},
)
data = response.json()  # {"url": "...", "filename": "...", "expires_in": 900}

Message object

MessageResponse (list items)

Field	Type	Description
`id`	UUID	Unique message identifier
`mailbox_id`	UUID	Owning mailbox
`thread_id`	UUID \| null	Conversation thread, if resolved
`message_id`	string	RFC 5322 Message-ID header value
`from_address`	string	Sender address
`to_addresses`	string[]	Primary recipients
`cc_addresses`	string[] \| null	CC recipients
`subject`	string \| null	Email subject line
`snippet`	string \| null	First ~200 chars of the plain-text body
`direction`	string	`inbound` or `outbound`
`status`	string	`queued`, `sent`, `delivered`, `bounced`, `failed`, or `received`
`is_read`	boolean	Whether the message has been read
`is_starred`	boolean	Whether the message is starred
`has_attachments`	boolean	Whether the message has attachments
`reply_to`	string \| null	`Reply-To` header (inbound: parsed from the original; outbound: caller-supplied override)
`import_job_id`	UUID \| null	Mail import job that created this historical message, or `null` for normal mail
`created_at`	string	Creation timestamp (ISO 8601)

MessageDetailResponse (single message)

Includes all MessageResponse fields plus:

Field	Type	Description
`body_text`	string \| null	Plain-text body
`body_html`	string \| null	HTML body
`bcc_addresses`	string[] \| null	BCC recipients
`in_reply_to`	string \| null	RFC 5322 In-Reply-To header
`references`	string[] \| null	RFC 5322 References headers
`attachment_metadata`	object[] \| null	Attachment descriptors for each file, including filename, content type, and size
`ses_message_id`	string \| null	Outbound provider message ID
`updated_at`	string	Last update timestamp (ISO 8601)
`reply_all_recipients`	object \| null	Server-suggested reply-all recipients (`{ to, cc }`), with the mailbox itself and BCC excluded — prefill editable To/Cc fields from this

​List messages

​Path parameters

​Query parameters

​Response (200)

​Code examples

​Get message

​Path parameters

​Response (200)

​Code examples

​Send message

​Path parameters

​Request body

​Request example

​Response (201)

​Custom signatures

​Idempotency

​Branding footer

​Open tracking

​Error responses

​Code examples

​Reply to everyone

​Path parameters

​Request body

​Recipient resolution

​Request example

​Response (201)

​Error responses

​Code examples

​Forward message

​Path parameters

​Request body

​Modes

​Forwarding behaviour

​Request example

​Response (201)

​Error responses

​Code examples

​Update message flags

​Path parameters

​Request body

​Code examples

​Delete message

​Path parameters

​Code examples

​Download attachment

​Path parameters

​Query parameters

​Response (302) — redirect mode (default)

​Response (200) — JSON mode

​Error responses

​Code examples

​Message object

​MessageResponse (list items)

​MessageDetailResponse (single message)

List messages

Path parameters

Query parameters

Response (200)

Code examples

Get message

Path parameters

Response (200)

Code examples

Send message

Path parameters

Request body

Request example

Response (201)

Custom signatures

Idempotency

Branding footer

Open tracking

Error responses

Code examples

Reply to everyone

Path parameters

Request body

Recipient resolution

Request example

Response (201)

Error responses

Code examples

Forward message

Path parameters

Request body

Modes

Forwarding behaviour

Request example

Response (201)

Error responses

Code examples

Update message flags

Path parameters

Request body

Code examples

Delete message

Path parameters

Code examples

Download attachment

Path parameters

Query parameters

Response (302) — redirect mode (default)

Response (200) — JSON mode

Error responses

Code examples

Message object

MessageResponse (list items)

MessageDetailResponse (single message)