Conversation API

The Conversation API puts two things in your team inbox. A form submission becomes a conversation in Todo. An email your app sends, such as a signup welcome, goes out from a shared address, and the reply lands with the team.

Call it from your server. It has no browser CORS, so a request from a web page fails.

Guides

This page is the reference. If you are trying to get a specific job done, start with the guide for it.

Get a key

Open Settings, then Developers, as a workspace owner. Choose a name, a primary use, the addresses the key may use, and the fewest permissions that work. Intray shows the key once. Store it in your server's secret store.

The same page shows the API base URL for your workspace. The examples use INTRAY_API_URL for that URL, including /v1, and INTRAY_API_KEY for the key. A key starts with intray_.

A contact form needs conversations:create only. GET /addresses works with any valid key.

A permission covers every conversation on the allowed addresses. That includes conversations started by people and by other keys. The primary use is a label. It grants nothing.

Rotate retires the old key for new requests at once and keeps retries working under the new key. Revoke stops new requests and blocks that key's queued email before it is sent. An email already handed to the mail provider cannot be recalled. To change permissions or addresses, create a new key.

Conventions

Every error has the same shape. The request ID is also in the X-Request-Id header. Send it to us when you report a problem.

{
  "error": {
    "code": "version_conflict",
    "message": "Conversation changed; read it again before retrying with a new idempotency key",
    "request_id": "5b0c1c9e-6f0e-4a57-9d0e-2f1b7c3a9e11"
  }
}

A 500 never includes internal detail. Its code is internal_error.

Endpoints

All paths are under /v1.

There is no endpoint that lists conversations. Store the id each write returns.

Find your address ID

Every write names the address it uses by ID.

curl "$INTRAY_API_URL/addresses" \
  -H "Authorization: Bearer $INTRAY_API_KEY"

{
  "data": [
    {
      "id": "<address ID>",
      "address": "support@example.com",
      "name": "Example support",
      "status": "active",
      "domain_status": "active",
      "can_send": false,
      "sending_reason": "This key does not have messages:send"
    }
  ]
}

can_send checks the key's permission, whether the address is ready to send, sending health, and remaining capacity. It does not reserve a place in the queue, and it says nothing about a particular recipient. sending_reason is null when can_send is true.

Create a conversation from a form

Save the form in your own database first. Then send it to Intray with an Idempotency-Key built from your saved record's ID, so a retry cannot create a second conversation.

curl "$INTRAY_API_URL/conversations" \
  -H "Authorization: Bearer $INTRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: form-8841" \
  -d '{
    "address_id": "<address ID>",
    "customer": { "email": "ada@example.com", "name": "Ada" },
    "subject": "Demo request",
    "initial_entry": {
      "type": "submission",
      "text": "Can we arrange a demo next week?",
      "fields": { "company": "Example company", "team size": "8" }
    },
    "external_id": "lead-8841"
  }'

{
  "conversation": {
    "id": "<conversation ID>",
    "address_id": "<address ID>",
    "subject": "Demo request",
    "customer": { "...": "..." },
    "triage": { "status": "todo", "snooze_until": null },
    "assignee_id": null,
    "version": "<version>",
    "origin": "<origin>",
    "external_id": "lead-8841",
    "created_at": 1790000000000,
    "updated_at": 1790000000000,
    "app_url": "<link to the conversation in Intray>"
  },
  "entry": { "id": "<entry ID>", "type": "submission" }
}

A submission sends no email. Someone on the team replies from the inbox, and that first reply is a normal email with the original subject. Submissions do not run the rules that fire when email arrives.

app_url opens the conversation for a signed-in team member. It is not a public link.

Send an email

curl "$INTRAY_API_URL/messages" \
  -H "Authorization: Bearer $INTRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-event-123" \
  -d '{
    "address_id": "<address ID>",
    "to": [{ "address": "ada@example.com", "name": "Ada" }],
    "subject": "Welcome",
    "text": "Thanks for signing up. Reply here if you need a hand.",
    "external_id": "signup-event-123"
  }'

{
  "message_id": "<message ID>",
  "conversation": { "id": "<conversation ID>", "...": "..." },
  "delivery": { "status": "queued" },
  "suppressed": []
}

202 means Intray queued the email. It does not mean delivered. Read delivery status to find out.

Supply text, html, or both. A new email starts in Done by default, so signup mail does not fill the team's Todo list. Send "initial_triage": "todo" when the team should see it.

Every email sent through the API carries an opt-out link for your workspace, and the headers support one-click unsubscribe. A recipient who opts out gets no further email from the workspace, from any key or address, including email already queued.

Pilot limits

• One to recipient per email.
• No Cc and no Bcc. A non-empty cc or bcc is rejected.
• No attachments.
• No custom From or Reply-To. The email goes out as the address in address_id.
• No batches, campaigns, or scheduled sends.

Composing from the inbox is not affected by these limits.

Reply to a conversation

Read the conversation first to get its version.

curl "$INTRAY_API_URL/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $INTRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-5521" \
  -d '{
    "expected_version": "<version from GET>",
    "to": [{ "address": "ada@example.com" }],
    "text": "Here are the details you asked for.",
    "triage_after_send": "preserve"
  }'

The response is the same 202 as Send an email.

triage_after_send is preserve by default. todo and done also need conversations:write. subject is optional on a reply. A reply to a conversation in Spam fails until someone changes its status.

Change status and assignee

curl -X PATCH "$INTRAY_API_URL/conversations/$CONVERSATION_ID" \
  -H "Authorization: Bearer $INTRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: triage-5521" \
  -d '{
    "expected_version": "<version from GET>",
    "triage": { "status": "snoozed", "snooze_until": 1790086400000 },
    "assignee_id": null
  }'

Send triage, assignee_id, or both. Sending neither returns 422.

snooze_until is accepted only with snoozed. assignee_id is the user ID of a current workspace member, or null to unassign. A status change made through the API does not run the rules that fire when a person changes status.

version changes when an email or submission arrives, and when status, snooze, or assignee change, from the API or the inbox. Delivery updates and reads do not change it. After 409 version_conflict, read the conversation again, decide whether your change still makes sense, and send it with the new version and a new Idempotency-Key.

Read entries

Entries are the emails and submissions in a conversation, newest first. Pass limit from 1 to 50. The default is 25.

curl "$INTRAY_API_URL/conversations/$CONVERSATION_ID/entries?limit=50" \
  -H "Authorization: Bearer $INTRAY_API_KEY"

{
  "data": [
    {
      "id": "<entry ID>",
      "type": "submission",
      "conversation_id": "<conversation ID>",
      "customer": { "email": "ada@example.com", "name": "Ada" },
      "text": "Can we arrange a demo next week?",
      "fields": { "company": "Example company", "team size": "8" },
      "content_trust": "untrusted_submission",
      "external_id": "lead-8841",
      "created_at": 1790000000000
    }
  ],
  "next_cursor": null
}

An entry with "type": "email" has the same fields as GET /messages/{id}. The API never returns internal notes, the built-in agent's activity, storage keys, or mail provider records.

Read delivery status

curl "$INTRAY_API_URL/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $INTRAY_API_KEY"

{
  "id": "<message ID>",
  "actor": { "type": "integration", "id": "<integration ID>" },
  "type": "email",
  "conversation_id": "<conversation ID>",
  "direction": "outbound",
  "subject": "Welcome",
  "from": { "...": "..." },
  "to": [{ "...": "..." }],
  "cc": [],
  "bcc": [],
  "body": {
    "text": { "kind": "inline", "text": "Thanks for signing up." },
    "html": { "kind": "none" }
  },
  "delivery": { "status": "delivered" },
  "content_trust": null,
  "external_id": "signup-event-123",
  "sent_at": 1790000000000
}

delivery is null on inbound email. On outbound email status is one of:

Intray never resends an unknown email on its own. Find out what happened before you send it again.

Each of body.text and body.html is { "kind": "inline", "text" }, { "kind": "url", "url", "size" } for a large body, or { "kind": "none" }. A download URL expires after 15 minutes. Fetch the message again for a fresh one.

actor is null on older email that has no recorded sender type.

Retries

Intray stores the response to each accepted write under your key, the operation, and the Idempotency-Key.

• Same key, same payload. Intray returns the original response and does nothing else. Field order does not matter. Use GET for the current delivery status and triage.
• Same key, different payload. 409 idempotency_conflict.
• Same key after seven days. 409 idempotency_expired. Intray never sends the email a second time. Do not retry it automatically.

When a call times out or returns 429 or 5xx, save a retry job and send the same key and the same payload after a delay. Do not make a new key for each attempt. Rotating the API key keeps your retry keys valid.