Every operation, generated from the spec

GET/api/v1/api-keys/validate

Check whether an API key is valid and see its status.

Looks up the key passed in the X-Api-Key header and reports whether it is currently valid, along with its name, workspace id, and status - active, revoked, or expired. A key that does not resolve at all still returns 200 with isValid set to false rather than an error; only a request with no X-Api-Key header at all is rejected with 401. Useful for confirming a newly created key works, or for diagnosing why a key you expected to work is being rejected elsewhere.

Requires ApiKey authentication.

Response 200

Responses

curl

curl https://api.communiqueue.com/api/v1/api-keys/validate \
  -H "X-Api-Key: cqk_..."

Node

const response = await fetch(
  'https://api.communiqueue.com/api/v1/api-keys/validate',
  {
    headers: {
      'X-Api-Key': process.env.COMMUNIQUEUE_API_KEY
    }
  }
)
const result = await response.json()
// result.isValid, result.status ('active' | 'revoked' | 'expired')

GET/api/v1/distribution-lists

Page through the workspace's distribution lists.

Returns lists with their id, name, description, member count, usage count (how many saved project/folder/template recipients reference the list), and timestamps. The optional name filter matches an exact list name, case-insensitively. Requires the key's ManageLists permission.

Requires ApiKey authentication.

Parameters

Response 200

Responses

curl

curl https://api.communiqueue.com/api/v1/distribution-lists \
  -H "X-Api-Key: cqk_..."

POST/api/v1/distribution-lists

Create a distribution list.

Creates an empty list with a name and optional description. The name must be 1 to 100 characters after trimming and unique in the workspace, case-insensitively - a duplicate name is a 409, not a validation error. Refused with distribution_lists.limit_exceeded past the plan's list count, in the same resourceType/current/limit billing-limit shape every other capacity limit uses. Returns 201 with a Location header pointing at the new list. Requires ManageLists.

Requires ApiKey authentication.

Request body

Response 201

Responses

curl

curl -X POST https://api.communiqueue.com/api/v1/distribution-lists \
  -H "X-Api-Key: cqk_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ops team", "description": "Internal ops alerts" }'

GET/api/v1/distribution-lists/{listId}

Fetch one distribution list.

Returns the list's id, name, description, member count, usage count, and timestamps. Requires ManageLists.

Requires ApiKey authentication.

Parameters

Response 200

Responses

curl

curl https://api.communiqueue.com/api/v1/distribution-lists/{listId} \
  -H "X-Api-Key: cqk_..."

PATCH/api/v1/distribution-lists/{listId}

Rename or re-describe a distribution list.

Changes the name and/or description; each is re-checked for length the same way creation is, and a name change into another list's name is a 409. A name of null keeps the current name; a description of null keeps the current description and an empty string clears it. Requires ManageLists.

Requires ApiKey authentication.

Parameters

Request body

Response 200

Responses

curl

curl -X PATCH https://api.communiqueue.com/api/v1/distribution-lists/{listId} \
  -H "X-Api-Key: cqk_..." \
  -H "Content-Type: application/json" \
  -d '{ "description": "Internal ops and billing alerts" }'

DELETE/api/v1/distribution-lists/{listId}

Delete a distribution list.

Deletes the list and its memberships. Refused with distribution_lists.in_use, naming every project, folder, and template that still saves this list as a default recipient (a usages array), until they stop referencing it. Requires ManageLists.

Requires ApiKey authentication.

Parameters

Responses

curl

curl -X DELETE https://api.communiqueue.com/api/v1/distribution-lists/{listId} \
  -H "X-Api-Key: cqk_..."

GET/api/v1/distribution-lists/{listId}/members

Page through a list's members.

Returns each member's email, name, custom fields, and when they were added. The optional search filter matches against email or name, case-insensitively. Requires ManageLists.

Requires ApiKey authentication.

Parameters

Response 200

Responses

curl

curl https://api.communiqueue.com/api/v1/distribution-lists/{listId}/members \
  -H "X-Api-Key: cqk_..."

POST/api/v1/distribution-lists/{listId}/members

Add or update up to 1,000 members in one all-or-nothing write.

A field key sent with a string sets it, a key sent as null deletes it, and a key not mentioned keeps its current value. A name left out or sent as null keeps the current name; an empty string clears it. Name and fields belong to the address across the whole workspace, so every list it is on sees them, and the 50-field cap counts the fields already stored. Fails entirely if any member is invalid: errorCode is the first rule that fired, errorCodes lists every distinct rule that fired, and itemErrors names every bad entry by index and code. A write that would take the list past 1,000 members is refused with distribution_lists.member_limit_reached, which also carries currentCount, attempted and limit. An empty or missing members array is refused with distribution_lists.batch_empty; to clear a list, send an empty members array to PUT /distribution-lists/{listId}/members instead. Requires ManageLists.

Requires ApiKey authentication.

Parameters

Request body

Response 200

Responses

curl

curl -X POST https://api.communiqueue.com/api/v1/distribution-lists/{listId}/members \
  -H "X-Api-Key: cqk_..." \
  -H "Content-Type: application/json" \
  -d '{ "members": [{ "email": "ada@example.com", "name": "Ada Lovelace" }] }'

PUT/api/v1/distribution-lists/{listId}/members

Replace a list's entire membership in one all-or-nothing write.

Members not in the new set are removed from this list only - their data on any other list they belong to is untouched. Name and fields merge the same way as adding, so a field left out is kept, not deleted. Unlike the other two member-write routes, an explicit empty members array is valid here and clears the whole list. Requires ManageLists.

Requires ApiKey authentication.

Parameters

Request body

Response 200

Responses

curl

curl -X PUT https://api.communiqueue.com/api/v1/distribution-lists/{listId}/members \
  -H "X-Api-Key: cqk_..." \
  -H "Content-Type: application/json" \
  -d '{ "members": [{ "email": "ada@example.com" }] }'

POST/api/v1/distribution-lists/{listId}/members/remove

Remove up to 1,000 members by email in one all-or-nothing write.

Addresses that are not members are ignored. Removing a contact's last list deletes their contact record too. An empty or missing emails array is refused with distribution_lists.batch_empty. Requires ManageLists.

Requires ApiKey authentication.

Parameters

Request body

Response 200

Responses

curl

curl -X POST https://api.communiqueue.com/api/v1/distribution-lists/{listId}/members/remove \
  -H "X-Api-Key: cqk_..." \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["ada@example.com"] }'

GET/api/v1/distribution-lists/{listId}/members/{email}

Fetch one member by email.

The email is URL-encoded in the path. Requires ManageLists.

Requires ApiKey authentication.

Parameters

Response 200

Responses

curl

curl https://api.communiqueue.com/api/v1/distribution-lists/{listId}/members/ada%40example.com \
  -H "X-Api-Key: cqk_..."

POST/api/v1/notifications/preview

Render a template against sample tags without sending anything.

Renders the live (or a pinned) version of the template with the supplied tags and returns the rendered output. Nothing is delivered and no delivery job is created. Only email templates are supported - previewing any other template type returns notifications.unsupported_notification_type. Useful in CI, or in an internal tool that needs to show what a send would look like before it goes out. Omit versionNumber to preview whatever version is currently live. A preview is refused when the send would be refused for its recipients or content: a list name that matches no list, a Marketing list send with copies, recipient variables in a Transactional version, or a reserved tag. It never expands a distribution list, so it cannot show who is on one.

Requires ApiKey authentication.

Request body

Response 200

Responses

curl

curl -X POST https://api.communiqueue.com/api/v1/notifications/preview \
  -H "X-Api-Key: cqk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "<your workspace id>",
    "templateId": "<your template id>",
    "tags": [{ "key": "firstName", "value": "Ada" }]
  }'

Node

const response = await fetch(
  'https://api.communiqueue.com/api/v1/notifications/preview',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.COMMUNIQUEUE_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tenantId: process.env.COMMUNIQUEUE_WORKSPACE_ID,
      templateId: process.env.COMMUNIQUEUE_TEMPLATE_WELCOME, // a template id is a GUID
      tags: [{ key: 'firstName', value: 'Ada' }]
    })
  }
)
const preview = await response.json()
// preview.email.renderedContent.subject / .body - what the send would render

POST/api/v1/notifications/send

Queue a templated notification for delivery.

Renders the template named by templateId with the supplied tags and queues it for delivery over whichever channel the template is configured for. The response is 202 Accepted, which means the notification has been queued, not that it has been delivered - track the actual delivery outcome in your workspace's delivery reports. Omit versionNumber to always send whatever version is currently live; pin it only when a specific published version must go out regardless of what gets published afterward. A webhook template additionally requires webhookOptions.urlOverride and a plan that includes webhook delivery. An email send to a workspace with no way to send (no email provider of its own connected and no managed sending on the account) returns 422 sending.no_route before anything is queued; its providerSettingsUrl and managedSendingUrl point at the two fixes, and managedSendingUrl is null for a complimentary account, which cannot buy managed sending and contacts support instead. On a workspace that sends through managed sending, the from address the send will use, emailOptions.fromAddress if you pass one and the address the version was saved with otherwise, must already be a verified domain or single sender; an unverified address returns 422 sender.not_verified before anything is queued. Name distribution lists in toLists, ccLists, bccLists or overrideLists; names match ignoring case, and a name that matches no list refuses the whole send. A Marketing version sends one email per To recipient, so a Marketing send that involves a list cannot also have Cc or Bcc recipients. A Transactional version sends one email that every To and Cc recipient sees, so put a list in bccLists to keep its members' addresses from each other. A send may reach at most 1,000 recipients, counting to, cc, bcc and overrideRecipients as named, or once saved recipients and distribution lists are expanded, and name at most 100 lists. It may carry at most 10 attachments. Size is bounded by the request body rather than by the attachments: a body over 10 MB is rejected with a bare 413 before the request is parsed, so it carries no errorCode. Base64 costs about a third on top of the file, so budget roughly 7 MB of actual attachment content. The monthly allowance is checked against the whole fan-out, so a send that would take the account past it is refused rather than partly delivered.

Requires ApiKey authentication.

Request body

Response 202

Responses

curl

curl -X POST https://api.communiqueue.com/api/v1/notifications/send \
  -H "X-Api-Key: cqk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "<your workspace id>",
    "templateId": "<your template id>",
    "tags": [{ "key": "firstName", "value": "Ada" }]
  }'

Node

const response = await fetch(
  'https://api.communiqueue.com/api/v1/notifications/send',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.COMMUNIQUEUE_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tenantId: process.env.COMMUNIQUEUE_WORKSPACE_ID,
      templateId: process.env.COMMUNIQUEUE_TEMPLATE_WELCOME, // a template id is a GUID
      tags: [{ key: 'firstName', value: 'Ada' }]
    })
  }
)
// 202 Accepted - the send is queued, not delivered; check your workspace's
// delivery reports for the outcome.