# OrgOrg API v1 — Comms — instructions for AI agents

This document describes the Comms endpoints of the OrgOrg v1 REST API. Fetch it from https://orgorg.com/docs/api/v1/comms/agents.md. The full API is documented at https://orgorg.com/docs/api/v1/agents.md.

## Basics

- Base URL: `https://orgorg.com`. All endpoint paths below are relative to it.
- Every request requires an `Authorization: Bearer <token>` header.
- `GET` endpoints take parameters in the URL query string. `POST` endpoints take a JSON body with a `Content-Type: application/json` header.
- All responses are JSON. A non-2xx status means the request failed; the body describes the problem.
- Endpoints are stable, but new response fields may be added without notice — ignore fields you do not recognize.

## Getting a token

Tokens are created by a signed-in user at https://orgorg.com/docs/credentials and inherit that user's permissions in their organization. If you do not have a token, ask your user to create one there. Verify a token works with:

```sh
curl "https://orgorg.com/api/v1/auth/test" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

A valid token returns `{ "ok": true, ... }`.

## 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. Human-readable docs: https://orgorg.com/docs/api/v1/comms

### 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).

Parameters: none.

Example request:

```sh
curl -X GET "https://orgorg.com/api/v1/comms/templates/list" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN"
```

Response shape:

```ts
{
  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.

Parameters:

- `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}}.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/comms/templates/create" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Split repair notice",
    "subject": "An update on your {{company}} workspace",
    "body": "Hi {{firstName}},\n\nWe merged the two {{company}} workspaces into one. Nothing is lost.\n"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

- `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.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/comms/templates/update" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "",
    "subject": "An update on your {{company}} workspace"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

- `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)".

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/comms/send/preview" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "",
    "recipientsText": "email, firstName, company\nna@nikhil.vc, Nikhil, nikhil.vc"
  }'
```

Response shape:

```ts
{
  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.

Parameters:

- `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.

Example request:

```sh
curl -X POST "https://orgorg.com/api/v1/comms/send" \
  -H "Authorization: Bearer $ORGORG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "",
    "recipientsText": "email, firstName, company\nna@nikhil.vc, Nikhil, nikhil.vc"
  }'
```

Response shape:

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