Download OpenAPI specification:Download
The Subtext API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Version 3 unlocks Subtext API features for all of your subscribers — whether created via API, List Import, Keyword Subscribe, Embed, or Sign Up Page. Using Version 3, you can now interact programatically with all of your Subtext subscribers.
Version 3 allows you to publish broadcasts to all of your subscribers or a targeted audience segment based on your subscribers' tags. This powerful feature represents an important milestone on the path to campaigns that are completely managed and/or automated via the Subtext API.
Version 3 allows you to list your campaign's existing tags, search for them by name, and create new tags. Better still, the returned tags include their active subscribers count. This feature is especially powerful when joined with the aforementioned targeted broadcasts functionality.
Version 3 allows you to take control of your data by attaching arbitrary key:value
metadata objects to your subscribers. You can use this to store external identifiers or link data from a CRM, for example. Whatever your use-case, this keeps you in control of your most valuable Subtext data objects.
Version 3 allows you to attach simple tags to your subscribers on creation. This allows for greater flexibility when using segmented broadcasts. It should also allow for some interesting new campaign engagement mechanisms.
Version 3 does away with the ExternalSubscriber
resource in favor of the underlying Subscriber
resource.
What this means in practice is that instead of using attributes of the ExternalSubscriber
resource to make requests, you should use attributes of the Subscriber
resource.
The Subscriber
resource is source-agnostic. While it does keep track of the source of a subscription, it doesn't provide different responses (or functionality) based on the source. This makes interactions with the Subtext API much simpler and more deterministic.
If you are migrating from Version 2 (or Version 1) of the Subtext API, your primary identifier for subscribers (subtext_uuid
) still refers to the ExternalSubscriber
resource and needs to be updated to refer to the Subscriber
resource. To aid you in migrating your data, we have provided /v3/migrate endpoints that will help you map your existing subtext_uuid
values to the v3-correct values. This is a simple operation that need only be run once in order to migrate your data.
While v1 and v2 of the Subtext API will remain fully functional, they are deprecated. We strongly recommend that all Subtext clients migrate to Version 3 as soon as possible.
Basic HTTP authentication
The Subtext API uses your campaign's secret key to authenticate requests. You can view and manage your campaign's secret key on the Campaign tab of your Subtext Campaign Dashboard.
Be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via HTTP Basic Auth. Provide your campaign's secret key as the basic auth username value. The password should be left blank. Basic Auth requires you to send the username:password
combination base64 encoded. So if your campaign's secret_key
is AbexNAMtQptCb22Afzf62a
, your Basic Auth Header will look like this:
Authorization: Basic QWJleE5BTXRRcHRDYjIyQWZ6ZjYyYTo=
QWJleE5BTXRRcHRDYjIyQWZ6ZjYyYTo=
is the base64 encoded form of AbexNAMtQptCb22Afzf62a:
(note the colon and blank password).
HTTPS is required
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
curl
In these docs, we use curl's -u option to pass the secret_key
unencoded. curl performs the base64 encoding for you. For example:
curl https://joinsubtext.com/v3/links \ -u "AbexNAMtQptCb22Afzf62a:"
basic
The Subscriber resource links your customer with their corresponding Subtext subscription.
The Subtext API's Subscriber endpoints enable you to do the following:
Creates a Subscriber resource that is subscribed to the authenticated Campaign resource.
phone_number required | |
postal_code | string <zip> Example: "10001" Postal code of the subscriber in 5-digit or 9-digit format. This field is required for campaigns that require postal codes. Otherwise it is optional. |
first_name | string Example: "Jason" First name of the subscriber. |
last_name | string Example: "Bourne" Last name of the subscriber. |
string <email> Example: "david.webb@gmail.com" Email address of the subscriber. | |
note | string Example: "Some info about this subscriber." Freeform text describing the subscriber. |
tags | Array of strings Example: "sports,Super Bowl" An array of strings with which to tag the Subscriber. |
metadata | object Example: "[object Object]" Set of key-value pairs that you can attach to a subscriber. This can be useful for storing additional information about the subscriber in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata. |
curl https://joinsubtext.com/v3/subscribers \ -u "a32f39fjas9dfan:" \ --data-urlencode phone_number="+13025556789" \ -d postal_code=10001 \ -d first_name=Jason \ -d last_name=Bourne \ --data-urlencode email="david.webb@gmail.com" \ --data-urlencode note="Some info about this subscriber." \ -d "tags[]"=sports \ --data-urlencode "tags[]"="Super Bowl" \ -d "metadata[customer_id]"=ADQ-39A-02998 \ -d "metadata[referral_id]"=b-299d-34da-zzor
{- "subscriber": {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-03-22T18:56:57.989Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": null,
- "resubscribed_at": null,
- "status": "Active",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
}
Retrieves all Subscriber resources belonging to the authenticated Campaign resource.
curl https://joinsubtext.com/v3/subscribers \ -u "a32f39fjas9dfan:"
{- "pagination": {
- "previous_page": null,
}, - "subscribers": [
- {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-03-22T18:56:57.989Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": null,
- "resubscribed_at": null,
- "status": "Active",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
]
}
Retrieves the Subscriber resource identified by the specified subtext_uuid
.
subtext_uuid required | string <uuid> Example: 61a8b662-e1a7-4457-ac08-baece296b4ab Subtext UUID of Subscriber to return |
curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab \ -u "a32f39fjas9dfan:"
{- "subscriber": {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-03-22T18:56:57.989Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": null,
- "resubscribed_at": null,
- "status": "Active",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
}
Retrieves the Subscriber resource identified by the specified phone_number
.
phone_number required |
curl https://joinsubtext.com/v3/subscribers/+13025556789 \ -u "a32f39fjas9dfan:"
{- "subscriber": {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-03-22T18:56:57.989Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": null,
- "resubscribed_at": null,
- "status": "Active",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
}
Unsubscribes the Subscriber resource identified by the specified subtext_uuid
.
subtext_uuid required | string <uuid> Example: 61a8b662-e1a7-4457-ac08-baece296b4ab Subtext UUID of Subscriber to unsubscribe |
curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/unsubscribe \ -u "a32f39fjas9dfan:" \ -X POST
{- "subscriber": {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-08-03T05:11:21.410Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": "2022-08-03T05:11:21.410Z",
- "resubscribed_at": null,
- "status": "Unsubscribed",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
}
Unsubscribes the Subscriber resource identified by the specified phone_number
.
phone_number required |
curl https://joinsubtext.com/v3/subscribers/+13025556789/unsubscribe \ -u "a32f39fjas9dfan:" \ -X POST
{- "subscriber": {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-08-03T05:11:21.410Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": "2022-08-03T05:11:21.410Z",
- "resubscribed_at": null,
- "status": "Unsubscribed",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
}
Resubscribes the Subscriber resource identified by the specified subtext_uuid
.
subtext_uuid required | string <uuid> Example: 61a8b662-e1a7-4457-ac08-baece296b4ab Subtext UUID of Subscriber to resubscribe |
curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/resubscribe \ -u "a32f39fjas9dfan:" \ -X POST
{- "subscriber": {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-11-03T14:44:31.190Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": null,
- "resubscribed_at": "2022-11-03T14:44:31.190Z",
- "status": "Active",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
}
Resubscribes the Subscriber resource identified by the specified phone_number
.
phone_number required |
curl https://joinsubtext.com/v3/subscribers/+13025556789/resubscribe \ -u "a32f39fjas9dfan:" \ -X POST
{- "subscriber": {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-11-03T14:44:31.190Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": null,
- "resubscribed_at": "2022-11-03T14:44:31.190Z",
- "status": "Active",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
}
The Message resource represents an SMS or MMS message sent by a Subtext campaign.
The Subtext API's Message endpoints enable you to do the following:
Creates a Message resource that is published to the specified Subscriber resource.
recipient_uuid required | string <uuid> Example: "61a8b662-e1a7-4457-ac08-baece296b4ab" Unique identifier representing the specific subscriber who will receive the message. |
body required | string [ 1 .. 640 ] characters Example: "Hey 👋 subscriber. Are you planning on watching the 🏀 game tonight?" Text content of the message. |
attachment_urls | Array of strings <uri> [ items <uri > ] Example: "https://picsum.photos/500/400.jpg,https://picsum.photos/seed/subtext/600/400.jpg" An array of media URLs that will be attached to the message. |
curl https://joinsubtext.com/v3/messages \ -u "a32f39fjas9dfan:" \ -d recipient_uuid=61a8b662-e1a7-4457-ac08-baece296b4ab \ --data-urlencode body="Hey 👋 subscriber. Are you planning on watching the 🏀 game tonight?" \ --data-urlencode "attachment_urls[]"="https://picsum.photos/500/400.jpg" \ --data-urlencode "attachment_urls[]"="https://picsum.photos/seed/subtext/600/400.jpg"
{- "message": {
- "recipient_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "to": "+12125551234",
- "body": "Hey 👋 subscriber. Are you planning on watching the 🏀 game tonight?",
- "attachment_urls": [
], - "created_at": "2022-03-22T18:56:57.989Z"
}
}
The Broadcast resource represents a broadcast created by a Subtext campaign.
The Subtext API's Broadcast endpoints enable you to do the following:
Retrieves all published Broadcast resources belonging to the authenticated Campaign resource.
curl https://joinsubtext.com/v3/broadcasts \ -u "a32f39fjas9dfan:"
{- "pagination": {
- "previous_page": null,
}, - "broadcasts": [
- {
- "subtext_uuid": "30e6fb89-034c-4ec8-bf62-87427da38854",
- "status": "published",
- "published_number": 149,
- "publish_date": "2024-04-24",
- "publish_time": "12:23:57 UTC",
- "send_at": null,
- "body": "Hey 👋 subscriber. Are you planning on watching the 🏀 game tonight?",
- "attachment_urls": [
], - "attach_vcard": false,
- "segment": {
- "audience": "all_subscribers",
- "tags": [ ]
}, - "engagement": "13.2%",
- "recipients": 3294,
- "replies_count": 435
}
]
}
Creates a Broadcast resource that is either:
body required | string [ 1 .. 640 ] characters Example: "Hello awesome subscribers. What do you think of the new logo?" Text content of the broadcast. | ||||
attachment_urls | Array of strings <uri> [ items <uri > ] Example: "https://picsum.photos/500/400.jpg,https://picsum.photos/seed/subtext/600/400.jpg" An array of media URLs that will be attached to the broadcast. | ||||
attach_vcard | boolean Example: "false" If set to | ||||
object Specify a subset of your audience to send the broadcast to. | |||||
| |||||
send_at | |||||
shorten_links | boolean Example: "false" If set to | ||||
publish_now | boolean Example: "false" If set to ⚠️ IMPORTANT
|
curl https://joinsubtext.com/v3/broadcasts \ -u "a32f39fjas9dfan:" \ --data-urlencode body="Hello awesome subscribers. What do you think of the new logo?" \ --data-urlencode "attachment_urls[]"="https://picsum.photos/500/400.jpg" \ --data-urlencode "attachment_urls[]"="https://picsum.photos/seed/subtext/600/400.jpg" \ --data-urlencode attach_vcard="false" \ -d "segment[audience]"=excluding_tags \ -d "segment[tag_ids][]"=68a45670-3005-4186-acc0-09ee01b4e82d \ -d "segment[tag_ids][]"=5e566b8e-5425-4152-aa14-e17bb4e8d2a9 \ --data-urlencode send_at="2025-05-04T15:30:00Z" \ --data-urlencode shorten_links="false" \ --data-urlencode publish_now="false"
{- "broadcast": {
- "subtext_uuid": "49083c84-82ae-4b09-b210-6b8f0a48d751",
- "status": "scheduled",
- "published_number": null,
- "publish_date": null,
- "publish_time": null,
- "send_at": "2025-05-04T15:30:00Z",
- "body": "Mother's Day is coming up. We've got our resident gift-giving expert here to answer your questions.",
- "attach_vcard": false,
- "segment": {
- "audience": "all_tags",
- "tags": [
- {
- "subtext_uuid": "f37cedf2-aaa1-4ccf-b879-26480ae6ed5c",
- "name": "Mother's Day",
- "active_subscribers_count": 397
}
]
}, - "engagement": null,
- "recipients": null,
- "replies_count": null
}
}
The Tag resource represents a tag that can be attached to subscribers of a Subtext campaign.
The Subtext API's Tag endpoints enable you to do the following:
Retrieves all Tag resources belonging to the authenticated Campaign resource.
If a query is provided, returns only those Tag resources matching the query.
query | string Examples:
The search query used to filter the results. |
curl https://joinsubtext.com/v3/tags?query=import \ -u "a32f39fjas9dfan:"
{- "pagination": {
- "previous_page": null,
}, - "tags": [
- {
- "subtext_uuid": "fb9af27f-2481-4684-8617-a2ea8d991bdf",
- "name": "Imported via Instagram",
- "active_subscribers_count": 351
}
]
}
Creates a Tag resource belonging to the authenticated Campaign resource.
name required | string [ 1 .. 255 ] characters Example: "VIP" The name of the tag. |
curl https://joinsubtext.com/v3/tags \ -u "a32f39fjas9dfan:" \ -d name=VIP
{- "tag": {
- "subtext_uuid": "e3f78dd9-07ee-4c57-849f-dff34b7e079f",
- "name": "VIP",
- "active_subscribers_count": 0
}
}
The Link resource represents a shortened link published by a Subtext campaign.
The Subtext API's Link endpoints enable you to do the following:
Retrieves all Link resources belonging to the authenticated campaign
curl https://joinsubtext.com/v3/links \ -u "a32f39fjas9dfan:"
{- "pagination": {
- "previous_page": null,
}, - "links": [
- {
- "subtext_uuid": "86d79d15-17cc-4540-8c94-f7f927b26efd",
- "broadcast_published_number": 14,
- "broadcast_publish_date": "2023-05-24",
- "broadcast_publish_time": "12:23:57 UTC",
- "clicks": 729,
- "clickthrough_rate": "21%"
}
]
}
The Subtext API's Migrate endpoints enable you to do the following:
Retrieves all ExternalSubscriber→Subscriber mappings belonging to the authenticated campaign.
curl https://joinsubtext.com/v3/migrate \ -u "a32f39fjas9dfan:"
{- "pagination": {
- "previous_page": null,
}, - "mappings": [
- {
- "v2_subtext_uuid": "a36cf5f3-5653-4307-a4f0-147b2f6d10c1",
- "v3_subtext_uuid": "dd116ba1-f1e3-4298-bca0-b52953204d79"
}, - {
- "v2_subtext_uuid": "77cd5f7b-3f39-4814-96ad-ac6bd3c52363",
- "v3_subtext_uuid": "2efea4ec-67a6-45e2-a720-60d5ab248537"
}
]
}
Retrieves the Subscriber resource associated with the specified ExternalSubscriber subtext_uuid
.
v2_subtext_uuid required | string <uuid> Example: 1f03d50c-f3d9-4cbe-ac30-6885e4e3114e Subtext UUID of ExternalSubscriber whose associated Subscriber you wish to return |
curl https://joinsubtext.com/v3/migrate/1f03d50c-f3d9-4cbe-ac30-6885e4e3114e \ -u "a32f39fjas9dfan:"
{- "subscriber": {
- "subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab",
- "created_at": "2022-03-22T18:56:57.989Z",
- "updated_at": "2022-03-22T18:56:57.989Z",
- "phone_number": "+13025556789",
- "first_name": "Jason",
- "last_name": "Bourne",
- "email": "david.webb@gmail.com",
- "note": "Some info about this subscriber.",
- "postal_code": "10001",
- "subscribed_at": "2022-03-22T18:56:58.810Z",
- "unsubscribed_at": null,
- "resubscribed_at": null,
- "status": "Active",
- "tags": [
- "sports",
- "Super Bowl"
], - "metadata": {
- "customer_id": "ADQ-39A-02998",
- "referral_id": "b-299d-34da-zzor"
}
}
}