Skip to main content
POST
JavaScript

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string

A unique key that makes this request idempotent. If Courier receives another request with the same Idempotency-Key, it returns the stored response from the first request without performing the operation again (including the original status code and any error). Use it to safely retry POST requests after network failures without risking duplicate sends. The key is scoped to this endpoint.

x-idempotency-expiration
string

How long the idempotency key remains valid, as a Unix epoch timestamp in seconds or an ISO 8601 date string. Only applies when Idempotency-Key is provided. If omitted, the key is retained for 25 hours; the maximum is 1 year.

Body

application/json

Request body for creating a new provider configuration.

provider
string
required

The provider key identifying the type (e.g. "sendgrid", "twilio"). Must be a known Courier provider — see the catalog endpoint for valid keys.

Maximum string length: 128
title
string

Optional display title. Omit to use "Default Configuration".

alias
string

Optional alias for this configuration.

settings
object

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. Set rate_limit to cap this configuration's send rate: { "rate": <number greater than 0>, "period": "second" | "minute" | "hour" }, e.g. { "rate": 0.5, "period": "minute" } for one send every 2 minutes. The interval between sends (period divided by rate) must be from 1 millisecond to 12 hours, otherwise the request returns a 400 InvalidRateLimit error. The limit applies per configuration and per environment (a test-environment configuration has its own limit). Sends above the rate are queued, not dropped, and changes take up to 60 seconds to apply. It has no effect on observability or CDP integrations, which do not send messages. Omit it or set it to null for no limit.

Response

Created

A configured provider in the workspace.

id
string
required

A unique identifier for the provider configuration.

title
string
required

Display title. Defaults to "Default Configuration" when not explicitly set.

provider
string
required

The provider key (e.g. "sendgrid", "twilio", "slack").

settings
object
required

Provider-specific settings (snake_case keys on the wire). rate_limit is this configuration's send rate limit, { "rate": number, "period": "second" | "minute" | "hour" }, or null for no limit.

created
integer
required

Unix timestamp (ms) of when the provider was created.

alias
string

Optional alias for this configuration.

updated
integer | null

Unix timestamp (ms) of when the provider was last updated.