Subtext API Reference (3.7.0)

Download OpenAPI specification:

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 programmatically 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.

Update a Subscriber

Version 3 introduces the ability to update an individual subscriber's information including first_name, last_name, email, postal_code, note and metadata.

Add or Remove Tags from a Subscriber

Version 3 introduces the ability to add or remove tags from a subscriber. This feature is especially useful for managing subscriber segments and targeted broadcasts.

List Links generated for broadcasts and direct messages

Version 3 introduces the ability to list all shortened links generated for direct messages via the Links resource, in addition to the previously included links generated for broadcasts. This feature can also be used to filter links by their context.

List Links generated for a subscriber

Version 3 introduces the ability to list all shortened links generated for a subscriber via the Message resource.

List reply Messages for a Broadcast

Version 3 introduces the ability to list all subscriber replies to a broadcast.

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.
Update your customer's Subtext subscriber information.
Add or Remove Tags from your customer's Subtext subscription.
Retrieve a subscriber's shortened links by its UUID.

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: {"customer_id":"ADQ-39A-02998","referral_id":"b-299d-34da-zzor"} 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 -G https://joinsubtext.com/v3/subscribers \
  -u "a32f39fjas9dfan:" \
  -d page=1

Response samples

200
400

Content type

application/json

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

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

Update Subscriber

Updates the Subscriber resource identified by the specified subtext_uuid with the provided parameters.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

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

Subtext UUID of Subscriber to update.

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

postal_code	string <zip> Example: "10001" Postal code of the subscriber in 5-digit or 9-digit format.
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.
metadata	object Example: {"customer_id":"ADQ-39A-02998","referral_id":"b-299d-34da-zzor"} 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/61a8b662-e1a7-4457-ac08-baece296b4ab \
  -u "a32f39fjas9dfan:" \
  -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 "metadata[customer_id]"=ADQ-39A-02998 \
  -d "metadata[referral_id]"=b-299d-34da-zzor \
  -X PUT

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

Update Subscriber by phone number

Updates the Subscriber resource identified by the specified phone_number with the provided parameters.

Authorizations:

basicAuth

path Parameters

phone_number

required

string <phone>

Example: +13025556789

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

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

postal_code	string <zip> Example: "10001" Postal code of the subscriber in 5-digit or 9-digit format.
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.
metadata	object Example: {"customer_id":"ADQ-39A-02998","referral_id":"b-299d-34da-zzor"} 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/+13025556789' \
  -u "a32f39fjas9dfan:" \
  -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 "metadata[customer_id]"=ADQ-39A-02998 \
  -d "metadata[referral_id]"=b-299d-34da-zzor \
  -X PUT

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

Add a Tag to a Subscriber

Adds a Tag to the Subscriber resource identified by the specified subtext_uuid. You can provide either the Tag's subtext_uuid or name.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

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

Subtext UUID of Subscriber to add a tag to.

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

object

subtext_uuid	string <uuid> Example: "f3e95934-f412-46f2-9762-2936ade111bd" The Subtext UUID of the tag to be added.
name	string Example: "VIP Supporter" The name of the tag to be added.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/add_tag \
  -u "a32f39fjas9dfan:" \
  -d "tag[subtext_uuid]"=f3e95934-f412-46f2-9762-2936ade111bd \
  --data-urlencode "tag[name]"="VIP Supporter"

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": null,
"status": "Active",
"tags": ["VIP Supporter"
],
"metadata": {"customer_id": "ADQ-39A-02998",
"referral_id": "b-299d-34da-zzor"
}
}
}

Add a Tag to a Subscriber by phone number

Adds a Tag to the Subscriber resource identified by the specified phone_number. You can provide either the Tag's subtext_uuid or name.

Authorizations:

basicAuth

path Parameters

phone_number

required

string <phone>

Example: +13025556789

Phone number (in E.164 format) of Subscriber to add a tag to.

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

object

subtext_uuid	string <uuid> Example: "f3e95934-f412-46f2-9762-2936ade111bd" The Subtext UUID of the tag to be added.
name	string Example: "VIP Supporter" The name of the tag to be added.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl 'https://joinsubtext.com/v3/subscribers/+13025556789/add_tag' \
  -u "a32f39fjas9dfan:" \
  -d "tag[subtext_uuid]"=f3e95934-f412-46f2-9762-2936ade111bd \
  --data-urlencode "tag[name]"="VIP Supporter"

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": null,
"status": "Active",
"tags": ["VIP Supporter"
],
"metadata": {"customer_id": "ADQ-39A-02998",
"referral_id": "b-299d-34da-zzor"
}
}
}

Remove a Tag from a Subscriber

Removes a Tag from the Subscriber resource identified by the specified subtext_uuid. You can provide either the Tag's subtext_uuid or name.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

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

Subtext UUID of Subscriber to remove a tag from.

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

object

subtext_uuid	string <uuid> Example: "f3e95934-f412-46f2-9762-2936ade111bd" The Subtext UUID of the tag to be removed.
name	string Example: "VIP Supporter" The name of the tag to be removed.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/remove_tag \
  -u "a32f39fjas9dfan:" \
  -d "tag[subtext_uuid]"=f3e95934-f412-46f2-9762-2936ade111bd \
  --data-urlencode "tag[name]"="VIP Supporter"

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": null,
"status": "Active",
"tags": ["sports",
"Super Bowl"
],
"metadata": {"customer_id": "ADQ-39A-02998",
"referral_id": "b-299d-34da-zzor"
}
}
}

Remove a Tag from a Subscriber by phone number

Removes a Tag from the Subscriber resource identified by the specified phone_number. You can provide either the Tag's subtext_uuid or name.

Authorizations:

basicAuth

path Parameters

phone_number

required

string <phone>

Example: +13025556789

Phone number (in E.164 format) of Subscriber to add a tag to.

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

object

subtext_uuid	string <uuid> Example: "f3e95934-f412-46f2-9762-2936ade111bd" The Subtext UUID of the tag to be removed.
name	string Example: "VIP Supporter" The name of the tag to be removed.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl 'https://joinsubtext.com/v3/subscribers/+13025556789/remove_tag' \
  -u "a32f39fjas9dfan:" \
  -d "tag[subtext_uuid]"=f3e95934-f412-46f2-9762-2936ade111bd \
  --data-urlencode "tag[name]"="VIP Supporter"

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": null,
"status": "Active",
"tags": ["sports",
"Super Bowl"
],
"metadata": {"customer_id": "ADQ-39A-02998",
"referral_id": "b-299d-34da-zzor"
}
}
}

List all shortened Links sent directly to a Subscriber via the API

Retrieves all shortened Link resources sent directly to a Subscriber via the API.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

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

Subtext UUID of Subscriber to return links for.

query Parameters

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

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl -G https://joinsubtext.com/v3/subscribers/61a8b662-e1a7-4457-ac08-baece296b4ab/links \
  -u "a32f39fjas9dfan:" \
  -d page=1

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/links?page=1",
"next_page": null
},
"links": [{"subtext_uuid": "4c995864-6f98-43c6-a379-fff67e16ac44",
"broadcast_published_number": null,
"broadcast_publish_date": null,
"broadcast_publish_time": null,
"message_publish_date": "2023-05-27",
"message_publish_time": "15:23:57 UTC",
"context": "Direct Message",
"shortlink": "https://subtxt.to/hijklmn",
"source_link": "https://en.wikipedia.org/wiki/Chowder",
"clicks": 2,
"clickthrough_rate": null
}
]
}

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.
shorten_links	boolean Example: "false" If set to `true`, all links in the body of the message will be shortened. Links must be prepended with https:// for successful shortlink conversion.

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" \
  --data-urlencode shorten_links="false"

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

Subtext UUID of Subscriber to return messages for.

query Parameters

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

Responses

Request samples

curl
Ruby
Python
Node.js
Go

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

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": null
},
"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.
Retrieve a broadcast's shortened links by its UUID.

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 -G https://joinsubtext.com/v3/broadcasts \
  -u "a32f39fjas9dfan:" \
  -d page=1

Response samples

200
400

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/broadcasts?page=1",
"next_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": ["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
}
}

List all shortened Links in a Broadcast

Retrieves all shortened Link resources in a Broadcast. This includes Link resources generated for attachments.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

Example: 30e6fb89-034c-4ec8-bf62-87427da38854

Subtext UUID of Broadcast to return links for.

query Parameters

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

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl -G https://joinsubtext.com/v3/broadcasts/30e6fb89-034c-4ec8-bf62-87427da38854/links \
  -u "a32f39fjas9dfan:" \
  -d page=1

Response samples

200
400
404

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/broadcasts/30e6fb89-034c-4ec8-bf62-87427da38854/links?page=1",
"next_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",
"message_publish_date": null,
"message_publish_time": null,
"context": "Broadcast",
"shortlink": "https://subtxt.to/abcdefg",
"source_link": "https://en.wikipedia.org/wiki/Mulligatawny",
"clicks": 729,
"clickthrough_rate": "21%"
}
]
}

List all replies to a Broadcast

Retrieves a paginated list of reply Message resources associated with the specified Broadcast resource.

Authorizations:

basicAuth

path Parameters

subtext_uuid

required

string <uuid>

Example: 30e6fb89-034c-4ec8-bf62-87427da38854

Subtext UUID of Broadcast to return replies for.

query Parameters

limit	integer Example: limit=20 Limit the number of replies per page.
page	integer Example: page=1 Page number for paginating the response.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl -G https://joinsubtext.com/v3/broadcasts/30e6fb89-034c-4ec8-bf62-87427da38854/replies \
  -u "a32f39fjas9dfan:" \
  -d limit=20 \
  -d page=1

Response samples

200
400
404

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/broadcasts/30e6fb89-034c-4ec8-bf62-87427da38854/replies?limit=20&page=1",
"next_page": "https://joinsubtext.com/v3/broadcasts/30e6fb89-034c-4ec8-bf62-87427da38854/replies?limit=20&page=2"
},
"broadcast": {"subtext_uuid": "30e6fb89-034c-4ec8-bf62-87427da38854"
},
"messages": [{"subscriber": {"subtext_uuid": "61a8b662-e1a7-4457-ac08-baece296b4ab"
},
"subtext_uuid": "e3f78dd9-07ee-4c57-849f-dff34b7e079f",
"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": "61a8b722-e1a7-4457-ac08-baece296b4ab"
},
"subtext_uuid": "a4d79c99-12fe-3dc7-8f33-a33f6b9e17ff",
"direction": "inbound",
"status": "received",
"from": "+12325555678",
"to": "+14155552671",
"body": "What a game!",
"attachment_urls": ["https://picsum.photos/500/400.jpg",
"https://picsum.photos/seed/subtext/600/400.jpg"
],
"created_at": "2023-05-04T19:59:51.837Z"
}
]
}

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 Tag resources matching it.

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 -G https://joinsubtext.com/v3/tags \
  -u "a32f39fjas9dfan:" \
  -d query=import \
  -d page=1

Response samples

200
400

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/tags?query=import&page=1",
"next_page": null
},
"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. This includes links generated via published broadcasts and direct messages.
Filter your campaign's published shortened links.

List all of your campaign's shortened Links

Retrieves all Link resources belonging to the authenticated Campaign resource. This includes Link resources generated for published broadcasts and direct messages. The context in which the Link was generated is indicated in the context field.

Authorizations:

basicAuth

query Parameters

context	string Enum: "broadcast" "dm" "all" Example: context=all Filter links by context.
page	integer Example: page=1 Page number for paginating the response.

Responses

Request samples

curl
Ruby
Python
Node.js
Go

curl -G https://joinsubtext.com/v3/links \
  -u "a32f39fjas9dfan:" \
  -d context=all \
  -d page=1

Response samples

200
400

Content type

application/json

{"pagination": {"previous_page": null,
"current_page": "https://joinsubtext.com/v3/links?context=all&page=1",
"next_page": null
},
"links": [{"subtext_uuid": "4c995864-6f98-43c6-a379-fff67e16ac44",
"broadcast_published_number": null,
"broadcast_publish_date": null,
"broadcast_publish_time": null,
"message_publish_date": "2023-05-27",
"message_publish_time": "15:23:57 UTC",
"context": "Direct Message",
"shortlink": "https://subtxt.to/hijklmn",
"source_link": "https://en.wikipedia.org/wiki/Chowder",
"clicks": 2,
"clickthrough_rate": null
},
{"subtext_uuid": "86d79d15-17cc-4540-8c94-f7f927b26efd",
"broadcast_published_number": 14,
"broadcast_publish_date": "2023-05-24",
"broadcast_publish_time": "12:23:57 UTC",
"message_publish_date": null,
"message_publish_time": null,
"context": "Broadcast",
"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 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 -G https://joinsubtext.com/v3/migrate \
  -u "a32f39fjas9dfan:" \
  -d page=1

Response samples

200
400

Content type

application/json

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

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.7.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

Update a Subscriber

Add or Remove Tags from a Subscriber

List Links generated for broadcasts and direct messages

List Links generated for a subscriber

List reply Messages for a Broadcast

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

Update Subscriber

Authorizations:

path Parameters

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

Responses

Request samples

Response samples

Retrieve your customer's Subtext subscription by phone number

Authorizations:

path Parameters

Responses

Request samples

Response samples

Update Subscriber by phone number

Authorizations:

path Parameters

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

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:

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

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

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