Create a subscription

POST

/api/v3/contacts/{email}/subscriptions

curl --request POST \
  --url https://api.tryletterhead.com/api/v3/contacts/example/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "api": true, "channel": "annas-channel", "status": 2 }'

• Production

Subscribes the contact to a channel. Requires status and either channel (a channel slug) or channelId (the channel’s numeric id, a legacy alternative — channel takes precedence when both are supplied).

Authorizations

• bearerAuth

Parameters

Path Parameters

email

required

string

The contact’s email address, URL-encoded.

Request Body ^required

Media type application/json

object

api

Required. Set to true to authenticate with an API key.

boolean

channel

A channel slug. Required unless channelId is supplied.

string

channelId

A channel’s numeric id (legacy alternative to channel).

integer

status

required

integer

Example

{
  "api": true,
  "channel": "annas-channel",
  "status": 2
}

Responses

201

201 Created. Returns the updated contact — same shape as GET /api/v3/contacts/{email}.

Media type application/json

object

items

The contact, with its updated subscription list. Full field list under GET /api/v3/contacts/{email}.

object

message

string

total

integer

Example

{
  "items": {
    "email": "[email protected]",
    "subscriptions": [
      {
        "channel": {
          "slug": "annas-channel",
          "name": "Anna's Channel"
        },
        "status": 2,
        "createdAt": "2026-08-30T15:01:21+00:00",
        "updatedAt": "2026-08-30T15:01:21+00:00"
      }
    ]
  },
  "message": "Subscription added.",
  "total": 1
}