Courier Providers API
The Providers API from Courier — 3 operation(s) for providers.
OpenAPI Specification
openapi: 3.0.1
info:
title: Courier Audiences Providers API
description: The Courier REST API.
version: "1.0"
servers:
- url: https://api.courier.com
description: Production
tags:
- name: Providers
paths:
/providers:
get:
description: List configured provider integrations for the current workspace. Supports cursor-based pagination.
operationId: providers_list
tags:
- Providers
parameters:
- name: cursor
in: query
description: Opaque cursor for fetching the next page.
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ProvidersListResponse'
summary: List providers
security:
- BearerAuth: []
post:
description: Create a new provider configuration. The `provider` field must be a known Courier provider key (see catalog).
operationId: providers_create
tags:
- Providers
parameters: []
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Provider'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
summary: Create a provider
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProvidersCreateRequest'
/providers/catalog:
get:
description: Returns the catalog of available provider types with their display names, descriptions, and configuration schema fields (snake_case, with `type` and `required`). Providers with no configurable schema return only `provider`, `name`, and `description`.
operationId: providers_catalog
tags:
- Providers
parameters:
- name: keys
in: query
description: Comma-separated provider keys to filter by (e.g. `sendgrid,twilio`).
required: false
schema:
type: string
- name: name
in: query
description: Case-insensitive substring match against the provider display name.
required: false
schema:
type: string
- name: channel
in: query
description: Exact match (case-insensitive) against the provider channel taxonomy (e.g. `email`, `sms`, `push`).
required: false
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ProvidersCatalogResponse'
summary: List available provider types
security:
- BearerAuth: []
/providers/{id}:
get:
description: Fetch a single provider configuration by ID.
operationId: providers_retrieve
tags:
- Providers
parameters:
- name: id
in: path
description: A unique identifier of the provider configuration.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Provider'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
summary: Get a provider
security:
- BearerAuth: []
put:
description: Replace an existing provider configuration. The `provider` key is required and determines which provider-specific settings schema is applied. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge). Changing the provider type for an existing configuration is not supported.
operationId: providers_update
tags:
- Providers
parameters:
- name: id
in: path
description: A unique identifier of the provider configuration to update.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Provider'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
summary: Update a provider
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProvidersUpdateRequest'
delete:
description: Delete a provider configuration. Returns 409 if the provider is still referenced by routing or notifications.
operationId: providers_delete
tags:
- Providers
parameters:
- name: id
in: path
description: A unique identifier of the provider configuration to delete.
required: true
schema:
type: string
responses:
'204':
description: Provider successfully deleted.
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Conflict'
summary: Delete a provider
security:
- BearerAuth: []
components:
schemas:
ProvidersCatalogResponse:
title: ProvidersCatalogResponse
type: object
description: Paginated list of available provider types with their configuration schemas.
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
items:
$ref: '#/components/schemas/ProvidersCatalogEntry'
required:
- paging
- results
NotFound:
title: NotFound
type: object
properties:
type:
type: string
enum:
- invalid_request_error
required:
- type
allOf:
- $ref: '#/components/schemas/BaseError'
ProvidersListResponse:
title: ProvidersListResponse
type: object
description: Paginated list of provider configurations.
properties:
paging:
$ref: '#/components/schemas/Paging'
results:
type: array
items:
$ref: '#/components/schemas/Provider'
required:
- paging
- results
ProvidersCatalogEntry:
title: ProvidersCatalogEntry
type: object
description: A provider type from the catalog. Contains the key, display name, description, and a `settings` object describing configuration schema fields.
properties:
provider:
type: string
description: The provider key (e.g. "sendgrid", "twilio").
name:
type: string
description: Human-readable display name.
description:
type: string
description: Short description of the provider.
channel:
type: string
description: Courier taxonomy channel (e.g. email, push, sms, direct_message, inbox, webhook).
settings:
type: object
description: Map of setting field names (snake_case) to their schema descriptors. Each descriptor has `type` and `required`. Empty when the provider has no configurable schema.
additionalProperties:
$ref: '#/components/schemas/ProviderSchemaField'
required:
- provider
- name
- description
- channel
- settings
Conflict:
title: Conflict
type: object
properties:
type:
type: string
enum:
- invalid_request_error
required:
- type
allOf:
- $ref: '#/components/schemas/BaseError'
BadRequest:
title: BadRequest
type: object
properties:
type:
type: string
enum:
- invalid_request_error
required:
- type
allOf:
- $ref: '#/components/schemas/BaseError'
BaseError:
title: BaseError
type: object
properties:
message:
type: string
description: A message describing the error that occurred.
required:
- message
ProvidersCreateRequest:
title: ProvidersCreateRequest
type: object
description: Request body for creating a new provider configuration.
properties:
provider:
type: string
maxLength: 128
description: The provider key identifying the type (e.g. "sendgrid", "twilio"). Must be a known Courier provider — see the catalog endpoint for valid keys.
title:
type: string
description: Optional display title. Omit to use "Default Configuration".
alias:
type: string
description: Optional alias for this configuration.
settings:
type: object
description: Provider-specific settings (snake_case keys). Defaults to an empty object when omitted. Use the catalog endpoint to discover required fields for a given provider — omitting a required field returns a 400 validation error.
additionalProperties: true
required:
- provider
ProvidersUpdateRequest:
title: ProvidersUpdateRequest
type: object
description: Request body for replacing an existing provider configuration. The `provider` key is required because it determines which provider-specific settings schema is validated against. Changing the provider type for an existing configuration is not supported. All other fields are optional — omitted fields are cleared from the stored configuration (this is a full replacement, not a partial merge).
properties:
provider:
type: string
maxLength: 128
description: The provider key identifying the type. Required on every request because it selects the provider-specific settings schema for validation.
title:
type: string
description: Updated display title.
alias:
type: string
description: Updated alias. Omit to clear.
settings:
type: object
description: Provider-specific settings (snake_case keys). Replaces the full settings object — omitted settings fields are removed. Use the catalog endpoint to check required fields.
additionalProperties: true
required:
- provider
ProviderSchemaField:
title: ProviderSchemaField
type: object
description: Describes a single configuration field in the provider catalog.
properties:
type:
type: string
description: The field's data type (e.g. "string", "boolean", "enum").
required:
type: boolean
description: Whether this field is required when configuring the provider.
values:
type: array
items:
type: string
description: Allowed values when `type` is "enum".
required:
- type
- required
Provider:
title: Provider
type: object
description: A configured provider in the workspace.
properties:
id:
type: string
description: A unique identifier for the provider configuration.
title:
type: string
description: Display title. Defaults to "Default Configuration" when not explicitly set.
provider:
type: string
description: The provider key (e.g. "sendgrid", "twilio", "slack").
alias:
type: string
description: Optional alias for this configuration.
settings:
type: object
description: Provider-specific settings (snake_case keys on the wire).
additionalProperties: true
created:
type: integer
description: Unix timestamp (ms) of when the provider was created.
updated:
type: integer
nullable: true
description: Unix timestamp (ms) of when the provider was last updated.
required:
- id
- title
- provider
- settings
- created
Paging:
title: Paging
type: object
properties:
cursor:
type: string
nullable: true
more:
type: boolean
required:
- more
securitySchemes:
BearerAuth:
type: http
scheme: bearer