Send your contact form to the inbox

Use this guide when your website has a contact, demo, or waitlist form and the team should answer those submissions from Intray. Each submission becomes a conversation in Todo on the address you choose, for example info. The conversation shows the person's message and any extra fields you send, such as company and team size, and the team replies to the person by email from the inbox.

Your server makes the request. Intray has no browser CORS and no anonymous endpoint, so a request from a web page fails.

Before you start

• A key with the conversations:create permission, limited to the address that should receive the submissions. A workspace owner creates it under Settings, then Developers. Intray shows the key once.
• The API base URL from the same screen. It already ends in /v1.
• The ID of the address. You read it from GET /addresses in the first step below.

Store all three as server secrets. The key must never appear in browser JavaScript, HTML, or a mobile app bundle.

INTRAY_API_URL=https://<your Intray API base>/v1
INTRAY_API_KEY=intray_...
INTRAY_ADDRESS_ID=<address ID>

Set it up

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

// Server only.
export type SavedSubmission = {
  id: string; // Primary key of the record in your own database.
  email: string;
  name?: string;
  message: string;
  company?: string;
  teamSize?: string;
};

export type ForwardResult =
  | { ok: true; conversationId: string; appUrl: string }
  | { ok: false; retry: boolean; code: string; requestId?: string };

export async function forwardSubmission(
  submission: SavedSubmission
): Promise<ForwardResult> {
  // Leave out empty values. Intray rejects a field that is not a string.
  const fields: Record<string, string> = {};
  if (submission.company) fields["company"] = submission.company;
  if (submission.teamSize) fields["team size"] = submission.teamSize;

  let response: Response;
  try {
    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": `form-${submission.id}`,
      },
      body: JSON.stringify({
        address_id: process.env.INTRAY_ADDRESS_ID,
        customer: { email: submission.email, name: submission.name },
        subject: "Website inquiry",
        initial_entry: {
          type: "submission",
          text: submission.message,
          fields,
        },
        external_id: submission.id,
      }),
      signal: AbortSignal.timeout(10_000),
    });
  } catch {
    // Timeout or network failure. Intray may or may not have the request.
    return { ok: false, retry: true, code: "network_error" };
  }

  const body = await response.json().catch(() => null);

  if (response.ok) {
    return {
      ok: true,
      conversationId: body.conversation.id,
      appUrl: body.conversation.app_url,
    };
  }

  return {
    ok: false,
    retry: response.status === 429 || response.status >= 500,
    code: body?.error?.code ?? "unknown",
    requestId: body?.error?.request_id,
  };
}

import { forwardSubmission, type SavedSubmission } from "./intray-forms";

// These stand for your own database code.
declare function listUnsentSubmissions(): Promise<SavedSubmission[]>;
declare function markSent(
  id: string,
  conversationId: string,
  appUrl: string
): Promise<void>;
declare function markFailed(
  id: string,
  code: string,
  requestId?: string
): Promise<void>;

// Run this every few minutes from your scheduler.
export async function retryUnsentSubmissions() {
  for (const submission of await listUnsentSubmissions()) {
    const result = await forwardSubmission(submission);
    if (result.ok) {
      await markSent(submission.id, result.conversationId, result.appUrl);
    } else if (!result.retry) {
      await markFailed(submission.id, result.code, result.requestId);
    }
    // A retryable failure stays unsent, and the next run picks it up.
  }
}

The field rules

The fields object is where extra form inputs go. Intray shows them under the message in the conversation.

• A submission can have up to 30 fields.
• A field name starts with a letter and has up to 64 letters, digits, spaces, or hyphens. team size is valid. team_size is rejected because of the underscore.
• A value is a string of up to 2,000 characters. Convert numbers and checkboxes to strings before you send them.
• initial_entry.text is required and holds 1 to 32,000 characters. If your form has no free text input, write a short sentence there, such as "Joined the waitlist".
• subject holds up to 500 characters with no line breaks.
• Any field the API does not know returns 422 invalid_request, and the message names the field.

external_id is your own reference, up to 200 characters, and the saved record's ID is a good value for it. It does not deduplicate. Only the Idempotency-Key prevents a second conversation.

Where the code runs

In Next.js, put the form endpoint in a Route Handler, for example app/api/contact/route.ts with an exported POST(request: Request) function. Save the record there, call forwardSubmission, and return your own response to the browser. The environment variables must not have the NEXT_PUBLIC_ prefix, because that prefix ships a value to the browser.

In Convex, a mutation cannot call fetch, so split the work. The mutation saves the submission and schedules an action with ctx.scheduler.runAfter(0, ...). The action calls Intray and then runs a mutation that stores the conversation ID. Set the three variables as environment variables on the Convex deployment and read them with process.env inside the action. A Convex cron job can run the retry function.

What the customer sees

Creating the conversation sends no email, so the person who filled in the form hears nothing from Intray at that point. If you want an immediate confirmation, send it from your own app. When someone on the team replies from the inbox, the customer receives a normal email from the shared address with the subject you set. Their answer comes back into the same conversation, and from then on it behaves like any other email thread.

A name sent with a submission never overwrites the name of a customer Intray already knows. Submissions also do not run the automation rules that fire when an email arrives, so a rule that labels incoming email does not label a form submission.

Check that it works

1. Submit the form once with your own email address.
2. Open the inbox in Intray. The conversation is in Todo on the address you chose, with your subject, the message, and the fields under it.
3. Reply from the inbox and confirm that the email reaches you with the same subject.
4. Answer that email and confirm that your answer appears in the same conversation.
5. Send the same saved record again, for example by running the retry job by hand. Intray returns the first response and no second conversation appears.

When it fails

Every error body has a request_id, and the same value is in the X-Request-Id header. Store it with the failed record and include it when you report a problem.

Next

• Link Intray conversations to your own records
• Update a conversation from your app