Courier Notification Templates API
The Notification Templates API from Courier — 8 operation(s) for notification templates.
OpenAPI Specification
openapi: 3.0.1
info:
title: Courier Audiences Notification Templates API
description: The Courier REST API.
version: "1.0"
servers:
- url: https://api.courier.com
description: Production
tags:
- name: Notification Templates
paths:
/notifications:
get:
description: List notification templates in your workspace.
operationId: notifications_list
tags:
- Notification Templates
parameters:
- name: cursor
in: query
description: Opaque pagination cursor from a previous response. Omit for the first page.
required: false
schema:
type: string
nullable: true
- name: notes
in: query
description: Include template notes in the response. Only applies to legacy templates.
required: false
schema:
type: boolean
nullable: true
- name: event_id
in: query
description: Filter to templates linked to this event map ID.
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationListResponse'
summary: List Notification Templates
security:
- BearerAuth: []
post:
description: Create a notification template. Requires all fields in the notification object. Templates are created in draft state by default.
operationId: notifications_create
tags:
- Notification Templates
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationTemplateResponse'
examples:
DraftCreated:
value:
id: nt_01abc123
name: Welcome Email
tags:
- onboarding
- welcome
brand:
id: brand_abc
subscription:
topic_id: marketing
routing:
strategy_id: rs_123
content:
version: '2022-01-01'
elements:
- type: channel
channel: email
elements:
- type: meta
title: Welcome!
- type: text
content: Hello {{data.name}}.
state: DRAFT
created: 1710000000000
creator: user_abc
updated: 1710000000000
updater: user_abc
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
examples:
ValidationError:
value:
type: invalid_request_error
message: 'notification.name: Required; notification.content: Required'
RoutingStrategyNotFound:
value:
type: invalid_request_error
message: Routing strategy rs_nonexistent not found
summary: Create Notification Template
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationTemplateCreateRequest'
examples:
DraftWithAllFields:
summary: Create a draft template with all fields populated
value:
notification:
name: Welcome Email
tags:
- onboarding
- welcome
brand:
id: brand_abc
subscription:
topic_id: marketing
routing:
strategy_id: rs_123
content:
version: '2022-01-01'
elements:
- type: channel
channel: email
elements:
- type: meta
title: Welcome!
- type: text
content: Hello {{data.name}}.
state: DRAFT
MinimalDraft:
summary: Create a minimal draft template
value:
notification:
name: Bare Minimum
tags: []
brand: null
subscription: null
routing: null
content:
version: '2022-01-01'
elements: []
AutoPublish:
summary: Create and immediately publish
value:
notification:
name: Auto-Published Template
tags:
- alerts
brand: null
subscription: null
routing: null
content:
version: '2022-01-01'
elements:
- type: channel
channel: email
elements:
- type: meta
title: Alert
- type: text
content: You have a new alert.
state: PUBLISHED
/notifications/{id}:
get:
description: Retrieve a notification template by ID. Returns the published version by default. Pass version=draft to retrieve an unpublished template.
operationId: notifications_retrieve
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Template ID (nt_ prefix).
required: true
schema:
type: string
- name: version
in: query
description: Version to retrieve. One of "draft", "published", or a version string like "v001". Defaults to "published".
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationTemplateResponse'
examples:
PublishedTemplate:
value:
id: nt_01abc123
name: Welcome Email
tags:
- onboarding
brand:
id: brand_abc
subscription:
topic_id: marketing
routing: null
content:
version: '2022-01-01'
elements:
- type: channel
channel: email
elements:
- type: meta
title: Welcome!
- type: text
content: Hello {{data.name}}.
state: PUBLISHED
created: 1710000000000
creator: user_abc
updated: 1710000001000
updater: user_def
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
summary: Get Notification Template
security:
- BearerAuth: []
put:
description: Replace a notification template. All fields are required.
operationId: notifications_replace
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Template ID (nt_ prefix).
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationTemplateResponse'
examples:
Replaced:
value:
id: nt_01abc123
name: Updated Name
tags:
- updated
brand: null
subscription: null
routing: null
content:
version: '2022-01-01'
elements:
- type: channel
channel: email
elements:
- type: meta
title: Updated
- type: text
content: Updated content.
state: PUBLISHED
created: 1710000000000
creator: user_abc
updated: 1710000001000
updater: user_def
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
examples:
ValidationError:
value:
type: invalid_request_error
message: 'notification.name: Required; notification.content: Required'
RoutingStrategyNotFound:
value:
type: invalid_request_error
message: Routing strategy rs_nonexistent not found
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
summary: Replace Notification Template
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationTemplateUpdateRequest'
examples:
FullReplace:
summary: Replace all fields
value:
notification:
name: Updated Name
tags:
- updated
brand: null
subscription: null
routing: null
content:
version: '2022-01-01'
elements:
- type: channel
channel: email
elements:
- type: meta
title: Updated
- type: text
content: Updated content.
state: PUBLISHED
delete:
description: Archive a notification template.
operationId: notifications_archive
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Template ID (nt_ prefix).
required: true
schema:
type: string
responses:
'204':
description: Successfully archived.
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
summary: Archive Notification Template
security:
- BearerAuth: []
/notifications/{id}/versions:
get:
description: List versions of a notification template.
operationId: notifications_listVersions
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Template ID (nt_ prefix).
required: true
schema:
type: string
- name: cursor
in: query
description: Opaque pagination cursor from a previous response. Omit for the first page.
required: false
schema:
type: string
- name: limit
in: query
description: Maximum number of versions to return per page. Default 10, max 10.
required: false
schema:
type: integer
default: 10
maximum: 10
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationTemplateVersionListResponse'
examples:
VersionHistory:
value:
versions:
- version: draft
created: 1774037925522
creator: user_abc
has_changes: true
- version: published:v003
created: 1774037924446
creator: user_abc
- version: v002
created: 1774037923967
creator: user_def
- version: v001
created: 1774037922000
creator: user_def
paging:
cursor: null
more: false
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
examples:
InvalidCursor:
value:
type: invalid_request_error
message: Invalid cursor format
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
summary: List Notification Template Versions
security:
- BearerAuth: []
/notifications/{id}/publish:
post:
description: Publish a notification template. Publishes the current draft by default. Pass a version in the request body to publish a specific historical version.
operationId: notifications_publish
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Template ID (nt_ prefix).
required: true
schema:
type: string
responses:
'204':
description: Successfully published, or already published with no changes (idempotent).
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
examples:
InvalidVersion:
value:
type: invalid_request_error
message: 'version: Expected format: v001, v002, etc.'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
VersionNotFound:
value:
type: invalid_request_error
message: Version not found for template nt_123
summary: Publish Notification Template
security:
- BearerAuth: []
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationTemplatePublishRequest'
examples:
PublishDraft:
summary: Publish the current draft (default)
value: {}
PublishSpecificVersion:
summary: Publish a specific historical version (rollback)
value:
version: v001
/notifications/{id}/content:
get:
description: Retrieve the content of a notification template. The response shape depends on whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use the `version` query parameter to select draft, published, or a specific historical version.
operationId: notifications_getContent
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Notification template ID (`nt_` prefix).
required: true
schema:
type: string
- name: version
in: query
description: Accepts `draft`, `published`, or a version string (e.g., `v001`). Defaults to `published`.
required: false
schema:
type: string
examples:
published:
value: published
summary: Current published version (default)
draft:
value: draft
summary: Current draft version
historical:
value: v001
summary: Specific historical version
responses:
'200':
description: Template content retrieved.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/NotificationContentGetResponse'
- $ref: '#/components/schemas/NotificationGetContentResponse'
examples:
V2Content:
summary: V2 elemental content response
value:
version: '2022-01-01'
elements:
- id: elem_channel_1
type: channel
checksum: abc123def456
locales:
es:
checksum: es_abc123
fr:
checksum: fr_abc123
elements:
- id: elem_meta_1
type: meta
checksum: meta_abc123
- id: elem_text_1
type: text
checksum: text_abc123
V1Content:
summary: V1 blocks/channels content response (legacy)
value:
blocks:
- id: block_1
type: text
content: Hello
channels:
- id: channel_1
type: email
checksum: legacy_checksum
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
summary: Get Notification Content
security:
- BearerAuth: []
put:
description: Replace the elemental content of a notification template. Overwrites all elements in the template with the provided content. Only supported for V2 (elemental) templates.
operationId: notifications_putContent
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Notification template ID (`nt_` prefix).
required: true
schema:
type: string
responses:
'200':
description: Content replaced.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationContentMutationResponse'
examples:
ContentUpdated:
summary: Content replaced successfully
value:
id: nt_01abc123
version: '2022-01-01'
elements:
- id: elem_1
checksum: abc123
- id: elem_2
checksum: def456
state: DRAFT
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
examples:
ValidationError:
value:
type: invalid_request_error
message: 'content: Required'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
summary: Put Notification Content
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationContentPutRequest'
examples:
ReplaceContent:
summary: Replace all content elements
value:
content:
version: '2022-01-01'
elements:
- type: channel
channel: email
elements:
- type: meta
title: Welcome!
- type: text
content: Hello {{data.name}}.
state: DRAFT
/notifications/{id}/elements/{elementId}:
put:
description: Update a single element within a notification template. Only supported for V2 (elemental) templates.
operationId: notifications_putElement
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Notification template ID (`nt_` prefix).
required: true
schema:
type: string
- name: elementId
in: path
description: Element ID within the template.
required: true
schema:
type: string
responses:
'200':
description: Element updated.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationContentMutationResponse'
examples:
ElementUpdated:
summary: Element updated successfully
value:
id: nt_01abc123
version: '2022-01-01'
elements:
- id: elem_1
checksum: abc123
- id: elem_2
checksum: def456
state: DRAFT
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
examples:
ValidationError:
value:
type: invalid_request_error
message: 'type: Required'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
ElementNotFound:
value:
type: invalid_request_error
message: Element elem_nonexistent not found in template nt_01abc123
summary: Put Notification Element
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationElementPutRequest'
examples:
UpdateTextElement:
summary: Update a text element
value:
type: text
data:
content: Updated text content
state: DRAFT
/notifications/{id}/locales/{localeId}:
put:
description: Set locale-specific content overrides for a notification template. Each element override must reference an existing element by ID. Only supported for V2 (elemental) templates.
operationId: notifications_putLocale
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Notification template ID (`nt_` prefix).
required: true
schema:
type: string
- name: localeId
in: path
description: Locale code (e.g., `es`, `fr`, `pt-BR`).
required: true
schema:
type: string
responses:
'200':
description: Locale overrides applied.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationContentMutationResponse'
examples:
LocaleUpdated:
summary: Locale content set successfully
value:
id: nt_01abc123
version: '2022-01-01'
elements:
- id: elem_1
checksum: abc123
- id: elem_2
checksum: def456
state: DRAFT
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
examples:
ValidationError:
value:
type: invalid_request_error
message: 'elements: Required'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
examples:
TemplateNotFound:
value:
type: invalid_request_error
message: Notification template nt_nonexistent not found
summary: Put Notification Locale
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationLocalePutRequest'
examples:
SetSpanishLocale:
summary: Set Spanish locale overrides
value:
elements:
- id: elem_1
content: Hola {{data.name}}.
- id: elem_2
title: Bienvenido!
state: DRAFT
/notifications/{id}/{submissionId}/checks:
get:
description: Retrieve the checks for a notification template submission.
operationId: notifications_getSubmissionChecks
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Notification template ID.
required: true
schema:
type: string
- name: submissionId
in: path
description: Submission ID.
required: true
schema:
type: string
responses:
'200':
description: Submission checks retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionChecksGetResponse'
summary: Get Submission Checks
security:
- BearerAuth: []
put:
description: Replace the checks for a notification template submission.
operationId: notifications_replaceSubmissionChecks
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Notification template ID.
required: true
schema:
type: string
- name: submissionId
in: path
description: Submission ID.
required: true
schema:
type: string
responses:
'200':
description: Submission checks replaced.
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionChecksReplaceResponse'
summary: Replace Submission Checks
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
checks:
type: array
items:
$ref: '#/components/schemas/BaseCheck'
required:
- checks
delete:
description: Cancel a notification template submission.
operationId: notifications_cancelSubmission
tags:
- Notification Templates
parameters:
- name: id
in: path
description: Notification template ID.
required: true
schema:
type: string
- name: submissionId
in: path
description: Submission ID.
required: true
schema:
type: string
responses:
'204':
description: Submission cancelled.
summary: Cancel Submission
security:
- BearerAuth: []
components:
schemas:
ElementalImageNode:
title: ElementalImageNode
type: object
description: Used to embed an image into the notification.
properties:
src:
type: string
description: The source of the image.
href:
type: string
nullable: true
description: A URL to link to when the image is clicked.
align:
$ref: '#/components/schemas/IAlignment'
nullable: true
description: The alignment of the image.
altText:
type: string
nullable: true
description: Alternate text for the image.
width:
type: string
nullable: true
description: CSS width properties to apply to the image. For example, 50px
required:
- src
allOf:
- $ref: '#/components/schemas/ElementalBaseNode'
MessageRoutingChannel:
title: MessageRoutingChannel
oneOf:
- type: string
- $ref: '#/components/schemas/MessageRouting'
MessageRoutingMethod:
title: MessageRoutingMethod
type: string
enum:
- all
- single
BadRequest:
title: BadRequest
type: object
properties:
type:
type: string
enum:
- invalid_request_error
required:
- type
allOf:
- $ref: '#/components/schemas/BaseError'
NotificationTemplateState:
title: NotificationTemplateState
type: string
description: Template state. Defaults to `DRAFT`.
enum:
- DRAFT
- PUBLISHED
default: DRAFT
NotificationContentMutationResponse:
title: NotificationContentMutationResponse
type: object
description: Shared mutation response for `PUT` content, `PUT` element, and `PUT` locale operations. Contains the template ID, content version, per-element checksums, and resulting state.
properties:
id:
type: string
description: Template ID.
version:
type: string
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/courier/refs/heads/main/openapi/courier-notification-templates-api-openapi.yml