Template Approval Workflow

Overview

The template approval workflow lets you require external review before publishing template changes. When enabled, templates enter a read-only state after submission and can only be published after checks are resolved via API.

How It Works

When a template is submitted for review, Courier emits a notification:submitted webhook. Your external system receives the event, runs its review process, and calls the Courier API to publish or reject the template.

Approval workflow diagram showing submission, webhook, review, and publish steps — Approval workflow flow

Enable Checks for a Template

Enable checks on each template that requires an approval workflow:

Open the notification template
Click the Settings gear
Navigate to the Checks tab
Enable custom checks

Checks tab in template settings with custom checks toggle — Enable custom checks in template settings

The template’s publish button is replaced with a Send for Review option.

Template showing Send for Review button — Send for Review button replaces Publish

After submission, the template enters a read-only state. No changes can be made to the latest draft until the submission is resolved or canceled.

Template in read-only state with cancel submission option — Template in read-only state after submission

Webhooks

Configure a webhook in Settings > Webhooks to receive submission events. The webhook fires when a notification is submitted, canceled, or published. Courier sends all event types to the same webhook endpoint, so filter on the type field.

Webhook configuration in Courier settings — Webhook Settings

Edit webhook dialog with URL and event configuration — Edit Webhook Dialog

Event Types

{
  "data": {
    "id": "<NOTIFICATION_ID>",
    "submission_id": "<SUBMISSION_ID>"
  },
  "type": "notification:submitted"
}

For other notification event types, see the webhook documentation. Once you receive a notification:submitted event, trigger your external approval workflow. When the review is complete, publish the template.

Fetching Content (Optional)

After receiving the notification:submitted event, you can retrieve the template content for use in your review process:

GET /notifications/:notification_id/draft/content

Sample notification template in the designer — Sample Template

Sample Response

{
  "blocks": [
    {
      "alias": "Greetings",
      "context": "This is where we greet a new user",
      "id": "block_43c114d9-9cfd-4340-808f-17e2fc7a4c87",
      "type": "text",
      "checksum": "fb60f2098fa407a4ff8d48e3e908d889",
      "content": "Hello <variable id=\"3\">{name}</variable>, Welcome to <highlight id=\"6\">Courier</highlight>!"
    },
    {
      "id": "block_f19dd58f-d32c-41b8-911c-239053d34803",
      "type": "markdown",
      "content": "Ready, <variable id=\"3\">{name}</variable>? Get started [here](http://daringfireball.net/projects/markdown/).",
      "checksum": "d06665ec3f663789db81474bc1a82fc5"
    }
  ],
  "channels": [
    {
      "id": "channel_f2e7b2e9-187f-40d9-9725-636d6c59833a",
      "type": "email",
      "content": {
        "subject": "New Subject"
      },
      "checksum": "96bcf212afa5cae1c7918280743aec71"
    }
  ],
  "checksum": "22d224a20345f1e3d3cf4c231243a747"
}

Checksums

Each block, channel, and notification includes an MD5 checksum. Use these to track content changes across submissions and manage translation workflows.

Publishing the Template

Once all checks are resolved, call the API to publish the template:

PUT /notifications/:notification_id/:submission_id/checks

{
  "checks": [
    {
      "status": "RESOLVED"
    }
  ]
}

To reject a submission, see Cancel a submission. You can also set the check status to FAILED or PENDING for more complex state management in your approval workflow.

Fetching Checks

GET /notifications/:notification_id/:submission_id/checks

Example: GET /notifications/SFTYJKSF0241SVH2TWY97TTFFTQG/1630424150210/checks

{
  "checks": [
    {
      "id": "B5BYH93H4D4XRPJBMZJGB43TJEZ3",
      "status": "PENDING",
      "type": "custom",
      "updated": 1630424150210
    }
  ]
}

Cancel a Submission

Cancel a submission by deleting it. This moves the template back to a draft state and sets all checks to FAILED. Once canceled, setting a check to RESOLVED will not publish that submission.

DELETE /notifications/:notification_id/:submission_id/checks

Submitted Keys

Submitted keys let you send notifications using draft content that has been submitted for review but not yet published. This is useful for testing changes before they go live.

Template State	What Submitted Key Uses
Published	Published notification content
Submitted for review	Latest draft content

Manage submitted keys in Settings > API Keys.

Submitted keys section in API Keys settings — Submitted Keys in API Key settings

Outbound Webhooks

Configure webhook endpoints for notification events

Send API

Send notifications using template IDs or event aliases

Platform

Developer Tools

Help

Template Approval Workflow

Overview

How It Works

Enable Checks for a Template

Webhooks

Event Types

Fetching Content (Optional)

Sample Response

Checksums

Publishing the Template

Fetching Checks

Cancel a Submission

Submitted Keys

Outbound Webhooks

Send API

​Overview

​How It Works

​Enable Checks for a Template

​Webhooks

​Event Types

​Fetching Content (Optional)

​Sample Response

​Checksums

​Publishing the Template

​Fetching Checks

​Cancel a Submission

​Submitted Keys

Outbound Webhooks

Send API

Overview

How It Works

Enable Checks for a Template

Webhooks

Event Types

Fetching Content (Optional)

Sample Response

Checksums

Publishing the Template

Fetching Checks

Cancel a Submission

Submitted Keys