Link a conversation to a record in your app

Add a nullable text column to the table that holds your records, for example intray_conversation_id on leads. Intray has no endpoint that lists or searches conversations, so this column is the only way your app can find the conversation again.

When you create the conversation, pass your record's ID as external_id. Intray stores it on the conversation and returns it on every read, so a person or a script looking at the conversation can tell which record it belongs to. It can be up to 200 characters.

external_id is a reference and Intray does not check it for uniqueness. If your server sends the same external_id twice with different Idempotency-Key values, Intray creates a second conversation. The Idempotency-Key header is what prevents duplicates, so build it from the same record ID and reuse it on every retry of that request.

Both ways of starting a conversation return it. Save conversation.id on your record in the same request handler.

// Server only. lead.id comes from the row you saved first.
export async function createLeadConversation(lead: {
  id: string;
  email: string;
  name: string;
  message: string;
}) {
  const response = await fetch(
    `${process.env.INTRAY_API_URL}/conversations`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.INTRAY_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `lead-${lead.id}`,
      },
      body: JSON.stringify({
        address_id: process.env.INTRAY_ADDRESS_ID,
        customer: { email: lead.email, name: lead.name },
        subject: "Website inquiry",
        initial_entry: { type: "submission", text: lead.message },
        external_id: lead.id,
      }),
    }
  );
  const result = await response.json();
  if (!response.ok) throw new Error(result.error.message);

  await db.leads.update(lead.id, {
    intray_conversation_id: result.conversation.id,
  });
  return result.conversation;
}

When someone opens the record in your admin, read the conversation from your server and pass the fields you need to the page.

// Server only.
export async function readConversation(conversationId: string) {
  const response = await fetch(
    `${process.env.INTRAY_API_URL}/conversations/${conversationId}`,
    { headers: { Authorization: `Bearer ${process.env.INTRAY_API_KEY}` } }
  );
  const conversation = await response.json();
  if (!response.ok) throw new Error(conversation.error.message);

  return {
    openInIntrayUrl: conversation.app_url,
    status: conversation.triage.status,
    snoozeUntil: conversation.triage.snooze_until,
    assigneeId: conversation.assignee_id,
    updatedAt: conversation.updated_at,
  };
}

Use app_url as the target of an "Open in Intray" link. It opens the conversation in the inbox for a team member who is signed in to Intray. It is not a public link, so a person without an Intray account in your workspace cannot read the conversation through it.

triage.status is todo, done, snoozed, or spam. assignee_id is the Intray user ID of the assigned team member, or null when nobody is assigned. The API returns the ID only, so keep a small map from Intray user ID to name in your app if you want to show a name.

Entries are the emails and form submissions in the conversation, newest first. Read them in pages of up to 50 and follow next_cursor until it is null. A page can come back empty and still carry a cursor, because Intray removes internal notes after it cuts the page.

// Server only.
export async function readEntries(conversationId: string) {
  const entries = [];
  let cursor: string | null = null;
  do {
    const url = new URL(
      `${process.env.INTRAY_API_URL}/conversations/${conversationId}/entries`
    );
    url.searchParams.set("limit", "50");
    if (cursor) url.searchParams.set("cursor", cursor);
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.INTRAY_API_KEY}` },
    });
    const page = await response.json();
    if (!response.ok) throw new Error(page.error.message);
    entries.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);
  return entries;
}

A submission entry has text and fields. An email entry has subject, from, to, direction, and a body whose text and html parts are each inline, a download URL that expires after 15 minutes, or absent. Read entries has the full shape.