Quickstart

First send in four steps

Wire the send once. After that, changing what the email says is a publish, not a deploy.

1. 1

   Create a workspace and a template

   Sign in, create your workspace, then connect your email provider in the workspace settings, or add managed sending under Billing, so the workspace has a way to send. Add a template inside a project. Write it in the visual editor or drop in HTML - variables use Handlebars syntax like {{firstName}}. Your work autosaves as a draft.

2. 2

   Test it, then publish

   Send yourself a test from the editor - it runs on the real pipeline but is flagged so it never appears in reports. When it looks right, publish. The draft becomes the live version.

3. 3

   Create an API key

   On the workspace's API keys page, create a key. It is shown once - store it as a secret. The key is scoped to that workspace.

4. 4

   Send by template id

   POST to the send endpoint with your workspace id, template id, and variable values. Omit versionNumber and every send uses whatever version is live - publish again later and the same call sends the new content.

The send call

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

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 and delivery is tracked in reports

Preview without sending

The preview endpoint renders the template with your variables and returns the result - nothing is delivered. Useful in CI or an internal admin.

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

Good to know

• Sends return 202 Accepted and are processed asynchronously; delivery status lands in your workspace reports.
• Omitted versionNumber means "whatever is live." Pin a specific version only when you need frozen content.
• A template with no published version returns 400 notifications.no_live_version - publish first.
• Bounced and complained recipients are suppressed automatically; manage the list in workspace settings.
• A workspace sends through the email provider you connect in its settings, or through managed sending if your account has it. With neither, a send is refused with 422 sending.no_route.
• With managed sending, your from address must be a verified sending domain or single sender first - an unverified address is refused rather than delivered unsigned. With your own provider, verify the domain there instead.
• Send to a named list instead of pasting addresses: add its name to emailOptions.toLists (or ccLists/bccLists), or replace every recipient with overrideLists. See Distribution lists.

Where to go next

• Authentication - the X-Api-Key header, creating a key, and what the key errors mean.
• Domain authentication - verify a sending domain or single sender before your first managed send.
• API reference - every operation, generated from the same document the API is tested against.
• Errors - the problem+json body shape, every error code, and the rate limits.
• Distribution lists - named recipient groups, managing members, and per-recipient personalization.