Create an SMS channel

POST

/api/v3/channels

curl --request POST \
  --url https://api.tryletterhead.com/api/v3/channels \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form api=true \
  --form brand=example \
  --form title=example \
  --form websiteUrl=example \
  --form phoneNumber=example \
  --form notes=example

• Production

Create an SMS channel under one of your company’s brands. Despite the shared /channels path, this is not a general-purpose “create a channel” endpoint — it only creates SMS channels. Email channels are created from the Letterhead app, not the API.

websiteUrl and phoneNumber are accepted and validated for the create form, but SMS sender provisioning is a separate connection step: only the title, a slug derived from the title, and notes (stored as the channel’s description) are persisted by this call.

This endpoint is gated behind an internal feature flag that is not yet enabled for any tenant. While it’s off, the endpoint returns 404 Not Found.

v3 endpoints expect a company API key.

Authorizations

• bearerAuth

Request Body ^required

Media type multipart/form-data

object

api

required

When set to true, this endpoint will accept authorization with your API Key.

string

Example

true

brand

required

Slug of the brand to create the channel under.

string

title

required

Channel title. Must contain at least one letter or number; also used to derive the channel’s slug.

string

websiteUrl

Optional. Must be a valid URL if present.

string

phoneNumber

Optional.

string

notes

Optional, up to 1000 characters. Stored as the channel’s description.

string

Responses

201

201 Created

Media type application/json

object

items

object

channel

string

title

string

type

string

message

string

total

integer

Example

{
  "items": {
    "channel": "an-example-sms-channel",
    "title": "An Example SMS Channel",
    "type": "sms"
  },
  "message": "SMS channel created successfully.",
  "total": 0
}

404

404 Not Found — the feature isn’t enabled for this tenant, or brand doesn’t match a brand this company owns.

Media type application/json

object

data

Array<object>

object

items

Array<object>

object

message

string

total

integer

Example

{
  "data": [],
  "items": [],
  "message": "Channel management is not enabled.",
  "total": 0
}

422

422 Unprocessable Entity — title reduces to an empty slug (for example, punctuation only).

Media type application/json

object

data

Array<object>

object

items

Array<object>

object

message

string

total

integer

Example

{
  "data": [],
  "items": [],
  "message": "Channel title must contain at least one letter or number.",
  "total": 0
}