Distribution lists

Named recipient groups

A distribution list is a named group of recipients that lives in CommuniQueue, scoped to a workspace. Use it as a saved default recipient on a project, folder, or template, or name it directly in a send call. Every plan includes lists; higher tiers include more of them, and every plan holds up to 1,000 members per list.

Concepts

A list has a name and an optional description. A member has an email address, an optional name, and up to 50 custom fields (string values) for per-recipient personalization - a plan tier, an account id, anything your template wants to reference. Adding the same email address to two different lists does not create two separate people: the name and fields belong to the address itself, not to the list.

Contacts are shared across lists

Because a member's name and fields belong to the address across the whole workspace, updating ada@example.com's name on one list changes what every other list she belongs to sees for her too. Removing her from her last list deletes her contact record entirely - there is no orphaned "contact with no list" state.

Managing lists

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" }'

{
  "id": "0f2b8a1e-6c9d-4b3a-9e7f-2d4c8a1b6e3f",
  "name": "Ops team",
  "description": "Internal ops alerts",
  "memberCount": 0,
  "usageCount": 0,
  "createdAt": "2026-09-27T12:00:00Z",
  "updatedAt": "2026-09-27T12:00:00Z"
}

Managing members

• Every write is all-or-nothing: if any member in the batch fails validation, nothing is written. The 422 response's errorCode is the first rule that fired, errorCodes lists every distinct rule that fired, and itemErrors names every bad entry by index and code.
• The same email appearing twice in one write is rejected outright, before anything is written.
• A field key you send with a value sets it; a field key sent as null deletes it; a field you don't mention is left as it was. Omitting name keeps the current name - send an empty string to clear it.
• PUT replaces which contacts are members of this list, never another list's view of a shared contact - an explicit empty members: [] clears the whole list in one call. POST members and POST members/remove treat that same empty array as a mistake and refuse it with distribution_lists.batch_empty.
• Adding members past 1,000 on one list is refused with distribution_lists.member_limit_reached. A list holds at most 1,000 members, which is also the most one send can reach, so remove members first to make room.

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", "fields": { "plan": "pro" } },
      { "email": "grace@example.com" }
    ]
  }'

{ "added": 2, "updated": 0, "removed": 0, "total": 2 }

Sending to a list

emailOptions on the send and preview calls gains four optional arrays of list names, matched case-insensitively: toLists, ccLists, and bccLists add every member of the named lists exactly as to, cc, and bcc add plain addresses. overrideLists joins overrideRecipients: together they replace every saved default recipient and every additive field above. An unknown list name fails the whole request with 422 notifications.email.distribution_list_not_found, naming every unknown name in the response. List membership is expanded once, when the send is accepted - a retry never re-reads live membership, so nobody is skipped or mailed twice if the list changes mid-delivery.

Whether members see each other depends on the version's email type. A Transactional version sends one email that every To and Cc recipient can see, list members included, so put a list in bccLists when its members should not see each other's addresses. A Marketing version sends one email per To recipient and would copy every Cc and Bcc recipient onto each of them, so a Marketing send that involves a list cannot also have Cc or Bcc recipients, saved ones included. It is refused with 422 notifications.email.marketing_list_with_copies.

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": "<a Marketing template id>",
    "tags": [],
    "emailOptions": { "toLists": ["Ops team"] }
  }'

Recipient variables

A Marketing template version renders once per To recipient (override recipients count as To), so it can reference the recipient it is being rendered for: {{recipient.email}}, {{recipient.name}}, and {{recipient.fieldKey}} for any custom field on that member. A recipient who came from a plain address rather than a list has only {{recipient.email}} - a missing field renders empty and is reported the same way a missing tag is today. A Transactional version - one shared copy for everyone - is refused at send time with 422 notifications.recipient_variables_require_marketing if its content references {{recipient.*}} at all. Because of this, recipient is a reserved tag key: a send whose tags include a key named recipient or starting with recipient. fails with 422 notifications.tags.recipient_reserved. The preview call accepts an optional top-level recipient object (email, name, fields) so a personalized template can be previewed with sample data. Preview renders the live version, or the published version you pin with versionNumber; there is no test send through the API. In the app, a test send of a draft takes a sample recipient's name and fields the same way.

Permissions and rate limits

Every route under /distribution-lists requires the key's ManageLists permission. /notifications/send and /notifications/preview require only Send, even when the request names a list - a send-only key can mail a list by name without ever being able to see or change who's on it. A key without the required permission gets 403 api_keys.permission_denied, naming the missing permission. Existing keys carry Send only, so nothing already integrated changes. Permissions are chosen when a key is created and can't be edited afterward - create a new key with the permissions you need and revoke the old one. Every /distribution-lists route sits behind its own public-lists rate-limit policy: 120 requests per minute per API key, and separately 120 requests per minute per source IP - both independent of the send and preview budget.

Error codes

See Errors and rate limits for the RFC 7807 body shape every one of these arrives in.