Comms

Your email templates with {{variables}}. List, create, and update them, preview a send to a recipient list, and send one personalized email per recipient from your own mailbox.

Working with an AI agent?or point it at the Comms markdown or the full-API markdown.

List email templates

GET

/api/v1/comms/templates/list

List your Comms email templates, newest first, with the {{variables}} each one uses. Requires comms:read (or :write).

Response:

{
  data: {
    id: string;
    name: string;
    subject: string;
    body: string;
    variables: string[];
    createdAt: number;
    updatedAt: number;
  }[]
}

Create email template

POST

/api/v1/comms/templates/create

Save a new email template. Write {{firstName}}, {{company}}, or any {{variable}} in the subject or body; a send fills it per recipient. Requires comms:write.

Parameter	Type	Description
name	string required	A short name for the template.
subject	string required	The subject line. It can hold {{variables}}.
body	string required	The plain-text body. It can hold {{variables}}.

Response:

{
  data: {
    id: string;
    name: string;
    subject: string;
    body: string;
    variables: string[];
    createdAt: number;
    updatedAt: number;
  };
  created: true
}

Update email template

POST

/api/v1/comms/templates/update

Change the name, subject, or body of one of your templates. Pass only the fields that change. Requires comms:write.

Parameter	Type	Description
templateId	string required	The id of the template.
name	string optional	The new name.
subject	string optional	The new subject line.
body	string optional	The new plain-text body.

Response:

{
  data: {
    id: string;
    name: string;
    subject: string;
    body: string;
    variables: string[];
    createdAt: number;
    updatedAt: number;
  }
}

Preview a send

POST

/api/v1/comms/send/preview

Render a template for every recipient without a send: the exact subject and body each one gets, the rows a missing {{variable}} holds back, invalid lines, duplicates, and the schedule (how many go today, how many spill to later days under the daily cap). Requires comms:write.

Parameter	Type	Description
templateId	string required	The id of the template.
recipientsText	string required	The recipient list: one per line. A first line with no @ names the columns, comma or tab separated, and each column is a {{variable}}. From a shell, pass "$(cat recipients.csv)".

Response:

{
  data: {
    recipients: {
      email: string;
      subject: string;
      bodyText: string;
      missing: string[];   // the variables this row has no value for
    }[];
    columns: string[];     // the variables the list gives
    invalid: string[];     // lines with no valid address
    duplicates: string[];
    summary: {
      sendable: number;
      blocked: number;
      perDay: { day: string; count: number }[];
      batchCap: number;
      batchCapExceeded: boolean;
      consented: boolean;  // your mailbox is enabled for sending
      accountEmail: string;
      variables: string[]; // the variables the template references
    };
  }
}

Send to a list

POST

/api/v1/comms/send

Send a template to every recipient in the list, one personalized email each, from your own mailbox. Sends are spaced minutes apart and spill to the next day past the daily cap. A row with a missing {{variable}} is skipped, never sent blank. Preview first. Requires comms:write, and a mailbox enabled for sending.

Parameter	Type	Description
templateId	string required	The id of the template.
recipientsText	string required	The recipient list, in the same form as the preview takes.
excludeEmails	object optional	A JSON array of addresses in the list to leave out of this send.

Response:

{
  data: {
    mergeBatchId: string;  // the batch, for the Outbox
    scheduled: number;
    skipped: number;       // rows a missing variable held back
  }
}