Subtext API Reference (3.5.0)

Download OpenAPI specification:Download

E-mail: api@joinsubtext.com Terms of Service

Introduction

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.

New Features

Universal Subscriber Management

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.

Publish, Schedule, and Draft Broadcasts

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.

List, Search, and Create Tags

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.

Subscriber Metadata

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.

Tag Subscribers on Creation

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.

List Messages for a Subscriber

Version 3 introduces the ability to list all messages from a conversation with a subscriber. This feature is available for both inbound and outbound messages.

Retrieve a Message

Version 3 introduces the ability to retrieve a message by its UUID. This feature is available for both inbound and outbound messages.

Breaking Changes

ExternalSubscriber Replaced by Subscriber

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.

Migrating from Earlier Versions

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.

Deprecations

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.

Authentication

basicAuth

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:"

Security Scheme Type: HTTP

HTTP Authorization Scheme: basic

Subscriber

The Subscriber resource links your customer with their corresponding Subtext subscription.

The Subtext API's Subscriber endpoints enable you to do the following:

Subscribe your customer to a Subtext campaign
List all of your customers' Subtext subscriptions
Retrieve your customer's Subtext subscription
Unsubscribe your customer from a Subtext campaign
Resubscribe your customer to a Subtext campaign

Subscribe your customer to a Subtext campaign

Creates a Subscriber resource that is subscribed to the authenticated Campaign resource.

Authorizations:

basicAuth

Request Body schema: application/x-www-form-urlencoded
required

phone_number required	string <phone> Example: "+13025556789" The subscriber's phone number (in E.164 format).
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.
email	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.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

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

Response samples

200
400
422

Content type

application/json

{"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"
}
}
}

List all of your customers' Subtext subscriptions

Retrieves all Subscriber resources belonging to the authenticated Campaign resource.

Authorizations:

basicAuth

query Parameters

page	integer Example: page=1 Page number for paginating the response.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers?page=1 \
  -u "a32f39fjas9dfan:"

Response samples

200
400

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/subscribers?page=1",
"next_page": "https://joinsubtext.com/v3/subscribers?page=2"
},
"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"
}
}
]
}

Retrieve your customer's Subtext subscription

Retrieves the Subscriber resource identified by the specified subtext_uuid.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

Example: 61a8b662-e1a7-4457-ac08-baece296b4ab

Subtext UUID of Subscriber to return

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab \
  -u "a32f39fjas9dfan:"

Response samples

200
400
404

Content type

application/json

Example

An active Subscriber

{"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"
}
}
}

Retrieve your customer's Subtext subscription by phone number

Retrieves the Subscriber resource identified by the specified phone_number.

Authorizations:

basicAuth

path Parameters

phone_number

required

string <phone>

Example: +13025556789

Phone number (in E.164 format) of Subscriber to return

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/+13025556789 \
  -u "a32f39fjas9dfan:"

Response samples

200
400
404

Content type

application/json

Example

An active Subscriber

{"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"
}
}
}

Unsubscribe your customer from a Subtext campaign

Unsubscribes the Subscriber resource identified by the specified subtext_uuid.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

Example: 61a8b662-e1a7-4457-ac08-baece296b4ab

Subtext UUID of Subscriber to unsubscribe

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/unsubscribe \
  -u "a32f39fjas9dfan:" \
  -X POST

Response samples

200
400
404
422

Content type

application/json

{"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"
}
}
}

Unsubscribe your customer from a Subtext campaign by phone number

Unsubscribes the Subscriber resource identified by the specified phone_number.

Authorizations:

basicAuth

path Parameters

phone_number

required

string <phone>

Example: +13025556789

Phone number (in E.164 format) of Subscriber to unsubscribe

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/+13025556789/unsubscribe \
  -u "a32f39fjas9dfan:" \
  -X POST

Response samples

200
400
404
422

Content type

application/json

{"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"
}
}
}

Resubscribe your customer to a Subtext campaign

Resubscribes the Subscriber resource identified by the specified subtext_uuid.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

Example: 61a8b662-e1a7-4457-ac08-baece296b4ab

Subtext UUID of Subscriber to resubscribe

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/resubscribe \
  -u "a32f39fjas9dfan:" \
  -X POST

Response samples

200
400
404
422

Content type

application/json

{"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"
}
}
}

Resubscribe your customer to a Subtext campaign by phone number

Resubscribes the Subscriber resource identified by the specified phone_number.

Authorizations:

basicAuth

path Parameters

phone_number

required

string <phone>

Example: +13025556789

Phone number (in E.164 format) of Subscriber to resubscribe

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/+13025556789/resubscribe \
  -u "a32f39fjas9dfan:" \
  -X POST

Response samples

200
400
404
422

Content type

application/json

{"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"
}
}
}

Message

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:

Send an SMS or MMS to your customer
List all messages to and from a subscriber
Retrieve a message by its UUID

Send an SMS or MMS message

Creates a Message resource that is published to the specified Subscriber resource.

Authorizations:

basicAuth

Request Body schema: application/x-www-form-urlencoded
required

recipient_uuid required	string <uuid> Example: "61a8b662-e1a7-4457-ac08-baece296b4ab" Unique identifier representing the specific subscriber who will receive the message. This should be set to the subscriber's `subtext_uuid`.
body required	string [ 1 .. 640 ] characters Example: "Hey 👋 subscriber. Are you planning on watching the 🏀 game tonight?" Text content of the message. If the message has no text content (sending an image-only MMS, for example), this value can be set to an empty string.
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. The files will be attached in the specified order.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

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"

Response samples

200
400
404
422

Content type

application/json

{"message": {"subscriber": {"subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab"
},
"subtext_uuid": "e3f78dd9-07ee-4c57-849f-dff34b7e079f",
"direction": "outbound",
"status": "queued",
"from": null,
"to": "+12125551234",
"body": "Hey 👋 subscriber. Are you planning on watching the 🏀 game tonight?",
"attachment_urls": ["https://picsum.photos/500/400.jpg",
"https://picsum.photos/seed/subtext/600/400.jpg"
],
"created_at": "2022-03-22T18:56:57.989Z",
"recipient_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab"
}
}

Retrieve a message

Retrieves a Message resource identified by the specified subtext_uuid.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

Example: e3f78dd9-07ee-4c57-849f-dff34b7e079f

Subtext UUID of Message to return

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/messages/e3f78dd9-07ee-4c57-849f-dff34b7e079f \
  -u "a32f39fjas9dfan:"

Response samples

200
400
404

Content type

application/json

Example

A received inbound Message

{"message": {"subscriber": {"subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab"
},
"subtext_uuid": "e3f78dd9-07ee-4c57-849f-dff34b7e079f",
"direction": "inbound",
"status": "received",
"from": "+12125551234",
"to": "+14155552671",
"body": "Yes, I'm planning on watching the game tonight. Go Lakers!",
"attachment_urls": [ ],
"created_at": "2022-03-22T18:56:57.989Z"
}
}

List all messages to and from a Subscriber

Retrieves all Message resources associated with the specified Subscriber resource.
If a direction is provided, returns only those Message resources matching the direction.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

Example: 61a8b662-e1a7-4457-ac08-baece296b4ab

Unique identifier representing the specific subscriber for whom to retrieve messages.
This should be set to the subscriber's subtext_uuid.

query Parameters

direction	string Enum: "inbound" "outbound" "all" Example: direction=all Filter messages by direction.
page	integer Example: page=1 Page number for paginating the response.
limit	integer Example: limit=20 Limit the number of messages per page.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/messages?direction=all&page=1&limit=20 \
  -u "a32f39fjas9dfan:"

Response samples

200
400
404

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/messages?direction=all&limit=20&page=1",
"next_page": "https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/messages?direction=all&limit=20&page=2"
},
"messages": [{"subscriber": {"subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab"
},
"subtext_uuid": "cbee8679-b168-434d-9c3d-550356f55d71",
"direction": "inbound",
"status": "received",
"from": "+12125551234",
"to": "+14155552671",
"body": "I'm at the game right now. Check out these seats!",
"attachment_urls": ["https://picsum.photos/id/585/800/600.jpg"
],
"created_at": "2023-05-04T20:01:23.162Z"
},
{"subscriber": {"subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab"
},
"subtext_uuid": "e3f78dd9-07ee-4c57-849f-dff34b7e079f",
"direction": "outbound",
"status": "delivered",
"from": null,
"to": "+12125551234",
"body": "Hey 👋 subscriber. Are you planning on watching the 🏀 game tonight?",
"attachment_urls": ["https://picsum.photos/500/400.jpg",
"https://picsum.photos/seed/subtext/600/400.jpg"
],
"created_at": "2023-05-04T19:59:51.837Z"
}
]
}

Broadcast

The Broadcast resource represents a broadcast created by a Subtext campaign.

The Subtext API's Broadcast endpoints enable you to do the following:

List your campaign's published broadcasts and their metrics
Publish a new broadcast to your subscribers
Schedule a new broadcast
Create a draft broadcast

List all of your campaign's published broadcasts

Retrieves all published Broadcast resources belonging to the authenticated Campaign resource.

Authorizations:

basicAuth

query Parameters

page	integer Example: page=1 Page number for paginating the response.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/broadcasts?page=1 \
  -u "a32f39fjas9dfan:"

Response samples

200
400

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/broadcasts?page=1",
"next_page": "https://joinsubtext.com/v3/broadcasts?page=2"
},
"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": ["https://picsum.photos/500/400.jpg",
"https://picsum.photos/seed/subtext/600/400.jpg"
],
"attach_vcard": false,
"segment": {"audience": "all_subscribers",
"tags": [ ]
},
"engagement": "13.2%",
"recipients": 3294,
"replies_count": 435
}
]
}

Create, Schedule, and/or Publish a new broadcast

Creates a Broadcast resource that is either:

Saved as a draft
Immediately published to the specified audience segment
Scheduled for publication to the specified audience segment

Authorizations:

basicAuth

Request Body schema: application/x-www-form-urlencoded
required

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.
The files will be attached in the specified order.
Limit 32MB per file.

attach_vcard

boolean

Example: "false"

If set to true, the broadcast will be sent with the campaign's vCard attached.

object

Specify a subset of your audience to send the broadcast to.
If you want the broadcast to go to all of your subscribers, you can ignore this or specify all_subscribers as the audience value.

audience required	string Enum: "all_subscribers" "all_tags" "any_tags" "excluding_tags" Example: "excluding_tags" Controls how the specified segment tags will be used to filter the recipients of the broadcast.
tag_ids	Array of strings <uuid> [ items <uuid > ] Example: "68a45670-3005-4186-acc0-09ee01b4e82d,5e566b8e-5425-4152-aa14-e17bb4e8d2a9" An array of tag ids that will be used to filter the recipients of the broadcast according to the segment audience. You can search the /v3/tags endpoint to retrieve tag ids.

send_at

string <date-time>

Example: "2025-05-04T15:30:00Z"

Date and time the broadcast will be published (in ISO 8601 format).
To ensure the broadcast is published at the correct time, please use UTC time.

shorten_links

boolean

Example: "false"

If set to true, all links in the body of the broadcast will be shortened.
Links must be prepended with https:// for successful shortlink conversion.

publish_now

boolean

Example: "false"

If set to true, the broadcast will be published immediately upon creation.

⚠️ IMPORTANT

If send_at is specified, publish_now will be ignored.
If send_at is not specified and publish_now is false, the broadcast will be saved as a draft.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

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"

Response samples

200
400
422

Content type

application/json

Example

A new Broadcast scheduled for publication at a future date

{"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.",
"attachment_urls": ["https://picsum.photos/500/400.jpg"
],
"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
}
}

Tag

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:

List your campaign's tags
Search your campaign's tags
Create a new tag

List or Search all of your campaign's tags

Retrieves all Tag resources belonging to the authenticated Campaign resource.
If a query is provided, returns only those Tag resources matching the query.

Authorizations:

basicAuth

query Parameters

query	string Examples: query=import - Return only those tags containing the substring "import". The search query used to filter the results.
page	integer Example: page=1 Page number for paginating the response.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/tags?query=import&page=1 \
  -u "a32f39fjas9dfan:"

Response samples

200
400

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/tags?page=1&query=import",
"next_page": "https://joinsubtext.com/v3/tags?page=2&query=import"
},
"tags": [{"subtext_uuid": "fb9af27f-2481-4684-8617-a2ea8d991bdf",
"name": "Imported via Instagram",
"active_subscribers_count": 351
}
]
}

Create a tag

Creates a Tag resource belonging to the authenticated Campaign resource.

Authorizations:

basicAuth

Request Body schema: application/x-www-form-urlencoded
required

name

required

string [ 1 .. 255 ] characters

Example: "VIP"

The name of the tag.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/tags \
  -u "a32f39fjas9dfan:" \
  -d name=VIP

Response samples

200
400
422

Content type

application/json

{"tag": {"subtext_uuid": "e3f78dd9-07ee-4c57-849f-dff34b7e079f",
"name": "VIP",
"active_subscribers_count": 0
}
}

Link

The Link resource represents a shortened link published by a Subtext campaign.

The Subtext API's Link endpoints enable you to do the following:

List your campaign's published shortened links and their metrics

List all of your campaign's shortened links

Retrieves all Link resources belonging to the authenticated campaign

Authorizations:

basicAuth

query Parameters

page	integer Example: page=1 Page number for paginating the response.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/links?page=1 \
  -u "a32f39fjas9dfan:"

Response samples

200
400

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/links?page=1",
"next_page": "https://joinsubtext.com/v3/links?page=2"
},
"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",
"shortlink": "https://subtxt.to/abcdefg",
"source_link": "https://en.wikipedia.org/wiki/Mulligatawny",
"clicks": 729,
"clickthrough_rate": "21%"
}
]
}

Migrate

The Subtext API's Migrate endpoints enable you to do the following:

List your campaign's ExternalSubscriber→Subscriber mappings
Retrieve the Subscriber resource for a given ExternalSubscriber

List all of your campaign's ExternalSubscriber→Subscriber mappings

Retrieves all ExternalSubscriber→Subscriber mappings belonging to the authenticated campaign.

Authorizations:

basicAuth

query Parameters

page	integer Example: page=1 Page number for paginating the response.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/migrate?page=1 \
  -u "a32f39fjas9dfan:"

Response samples

200
400

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/migrate?page=1",
"next_page": "https://joinsubtext.com/v3/migrate?page=2"
},
"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"
}
]
}

Retrieve the Subscriber resource for a given ExternalSubscriber

Retrieves the Subscriber resource associated with the specified ExternalSubscriber subtext_uuid.

Authorizations:

basicAuth

path Parameters

v2_subtext_uuid

required

string <uuid>

Example: 1f03d50c-f3d9-4cbe-ac30-6885e4e3114e

Subtext UUID of ExternalSubscriber whose associated Subscriber you wish to return

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/migrate/1f03d50c-f3d9-4cbe-ac30-6885e4e3114e \
  -u "a32f39fjas9dfan:"

Response samples

200
400
404

Content type

application/json

{"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"
}
}
}

Subtext API Reference (3.5.0)

Introduction

New Features

Universal Subscriber Management

Publish, Schedule, and Draft Broadcasts

List, Search, and Create Tags

Subscriber Metadata

Tag Subscribers on Creation

List Messages for a Subscriber

Retrieve a Message

Breaking Changes

ExternalSubscriber Replaced by Subscriber

Migrating from Earlier Versions

Deprecations

Authentication

basicAuth

Subscriber

Subscribe your customer to a Subtext campaign

Authorizations:

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Request samples

Response samples

List all of your customers' Subtext subscriptions

Authorizations:

query Parameters

Responses

Request samples

Response samples

Retrieve your customer's Subtext subscription

Authorizations:

path Parameters

Responses

Request samples

Response samples

Retrieve your customer's Subtext subscription by phone number

Authorizations:

path Parameters

Responses

Request samples

Response samples

Unsubscribe your customer from a Subtext campaign

Authorizations:

path Parameters

Responses

Request samples

Response samples

Unsubscribe your customer from a Subtext campaign by phone number

Authorizations:

path Parameters

Responses

Request samples

Response samples

Resubscribe your customer to a Subtext campaign

Authorizations:

path Parameters

Responses

Request samples

Response samples

Resubscribe your customer to a Subtext campaign by phone number

Authorizations:

path Parameters

Responses

Request samples

Response samples

Message

Send an SMS or MMS message

Authorizations:

Request Body schema: application/x-www-form-urlencodedrequired

Responses

Request samples

Response samples

Retrieve a message

Authorizations:

path Parameters

Responses

Request samples

Response samples

List all messages to and from a Subscriber

Authorizations:

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required

Request Body schema: application/x-www-form-urlencoded
required