Documentation Powered by ReDoc

SimpleTexting REST API Documentation (1.0.0)

Download OpenAPI specification:Download

Introduction

Thousands of businesses rely on SimpleTexting to communicate with their audience via text message. With our API, developers can access many of our platform’s features and integrate them with other websites or applications.

This document details the available SimpleTexting API functions and their parameters.

To prevent spam, our API is by approval only. If you’d like access, sign up for a trial account and email [email protected] with details about your use case.

How it works

Our API is organized around REST. It uses standard HTTP response codes and authentication. Before you get started, there a few things to keep in mind:

  • When using the POST request, you must specify that content-type is application/x-www-form-urlencoded.
  • The default response for all requests is JSON. To use XML, you must change the value for the Accept request header to application/xml.
  • If the message contains a link from a common third-party link shortener such a bit.ly, it will appear from our URL shortener instead and occupy 20 characters. Learn more.

Authentication

Each time you make a request to our API, we use an API token to authenticate your account. API requests without authentication will fail. Your API token can be found under settings.

Please be sure to keep your token secure. Don’t share it in any public areas such as GitHub, client-side code, etc.

Bearer Token

Our API supports Bearer Token authentication.

To understand more about bearer tokens, please take a look at the following resource.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer

Api Token Auth (Deprecated)

Using your API key, you can authenticate your account directly in the URL parameter of your request. Please note: Api token auth is only available for users that started using the v1 api before 09.01.2021

Security Scheme Type API Key
Query parameter name: token

Webhooks

Use webhooks to communicate between the SimpleTexting platform and your server. Webhooks can be used to forward messages as well as provide info about unsubscribes and message delivery.

SimpleTexting can trigger webhooks for new incoming messages, delivery reports and unsubscribes. Now you can build scripts that interpret and respond to events that occur in your SimpleTexting account!

To set the URLs for your webhooks, visit the Webhooks tab on the API section of settings.

Delivery report

Triggers when an outgoing message is reported as delivered or undelivered by the carrier.

Example


http://www.yourdomain.com/delivery.php

with JSON body: { 'id': '5bec5b9d0a975a238808ffb2', 'type': 'SMS', 'status': 'delivered', 'destination': '1234567890', 'carrier': 'Sprint' }

http://www.yourdomain.com/delivery.php has been set as delivery report webhook for this example. The SimpleTexting server will invoke the given call when a message with the smsid 5bec5b9d0a975a238808ffb2 is delivered.

Sent as POST.

query Parameters
id
string
Example: id=5bec5b9d0a975a238808ffb2

The unique identifier which was provided in message sending response (smsid).

type
string
Enum: "SMS" "MMS"
Example: type=SMS

Type of a message the delivery report has been received for.

SMS or MMS

status
string
Enum: "delivered" "undelivered"
Example: status=delivered

Delivered (The carrier has provided confirmation of message delivery.)

Undelivered (Among other reasons, this may occur if the handset was unreachable, the number was a landline, or the carrier blocked the content.)

destination
string
Example: destination=9545551234

The phone number to which the message was sent.

carrier
string
Example: carrier=Sprint

The message recipient’s telecom provider (e.g. AT&T, Verizon).

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://yourdomain.com/v1/delivery.php?id=5bec5b9d0a975a238808ffb2&type=SMS&status=delivered&destination=9545551234&carrier=Sprint");

CURLcode ret = curl_easy_perform(hnd);

Unsubscribe report

Triggers on any unsubscribe. This can be a subscriber texting STOP or a user manually blocking a subscriber via the SimpleTexting UI.


Example


http://www.yourdomain.com/unsubcscribe.php

With JSON body: { 'phone': '9545551234' }

http://www.yourdomain.com/unsubscribe.php has been set as the unsubscribe report URL for this example. The SimpleTexting server will invoke the given call when the subscriber with the number 954-555-1234 unsubscribes.

query Parameters
phone
string
Example: phone=9545551234

Subscriber’s phone number.

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://yourdomain.com/v1/unsubscribe.php?phone=9545551234");

CURLcode ret = curl_easy_perform(hnd);

SMS forwarding webhook

Configure this webhook to listen for incoming SMS messages.


Example


If http://www.yourdomain.com/receivesms.php is set as the URL for message forwarding then

http://www.yourdomain.com/receivesms.php?from=8017555038&to=555888&subject=&text=Hello%20my%20friend

is invoked when 801-755-5038 texts Hello my friend to 555888.

query Parameters
from
string
Example: from=8017555038

10-digit phone number message originated from

to
string
Example: to=555888

10-digit phone number message is sent to

subject
string
Example: subject=

The subject of a message (usually blank)

text
string
Example: text=Hello my friend

The body of receiving message that was texted in by the originating phone number

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://yourdomain.com/v1/receivesms.php?from=8017555038&to=555888&subject=%20&text=Hello%20my%20friend");

CURLcode ret = curl_easy_perform(hnd);

MMS forwarding webhook

Configure this webhook to listen for incoming MMS messages.


Example


Unlike SMS messages, which are forwarded using GET, MMS messages are forwarded using POST.

http://www.yourdomain.com/receivemms.php

With JSON body: { 'from': '8017555038', 'to': '555888', 'subject': '', 'text': 'Here's some pictures', 'attachments': ['https://app.simpletexting.com/files/picture1.png', 'https://app.simpletexting.com/files/picture2.png'] }

For example, if 801-755-5038 texts “Here's some pictures” to 555888, the above query string would be sent in the HTTP message body.

query Parameters
from
string
Example: from=8017555038

10-digit phone number message originated from

to
string
Example: to=555888

10-digit phone number message is sent to

subject
string
Example: subject=

The subject of a message

text
string
Example: text=Here are your pictures

The body of receiving message that was texted in by the originating phone number

attachments
string
Example: attachments=[ https://app.simpletexting.com/files/picture1.png, https://app.simpletexting.com/files/picture2.png]

The body of receiving message that was texted in by the originating phone number

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://yourdomain.com/v1/receivemms.php?from=8017555038&to=555888&subject=%20&text=Here%20are%20your%20pictures&attachments=%5B%20https%3A%2F%2Fapp.simpletexting.com%2Ffiles%2Fpicture1.png%2C%20https%3A%2F%2Fapp.simpletexting.com%2Ffiles%2Fpicture2.png%5D");

CURLcode ret = curl_easy_perform(hnd);

Configure SMS forwarding

Configure or update settings for message forwarding from your account. All incoming messages can be forwarded to an email, phone or URL you specify. (Messages don’t have to be forwarded to all three, but at least one must be specified.) If the URL is provided, the SimpleTexting server forwards received messages by making an HTTP GET request to the URL.

Forwarding via the API can only be configured for SMS messages. MMS forwarding must be configured by visiting the Webhooks tab on your dashboard.

Authorizations:
None
query Parameters
email
string

We will forward incoming messages to the email address for free

url
string

We will forward incoming messages to this URL.

phone
string

We will forward incoming messages to this mobile number.

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/forward/setup?token=YOUR_API_TOKEN&email=SOME_STRING_VALUE&url=SOME_STRING_VALUE&phone=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
incorrectPhoneNumber
invalidEmail
invalidURL
{
  • "code": 1,
  • "message": "The request succeeded"
}

Messages

In SimpleTexting, users can send and receive messages. With our API, this can be done programmatically.

Send SMS message

Send a text message to an individual contact. Each outgoing SMS message is worth 1 credit.

If the message contains a link from a common third-party link shortener such as bit.ly, it will appear from our URL shortener instead and occupy 20 characters. Learn more

Authorizations:
None
query Parameters
phone
required
string

10-digit phone number to send the message to

message
required
string

The body of your message (Note, cannot exceed 160 characters)

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/send?token=YOUR_API_TOKEN&phone=SOME_STRING_VALUE&message=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
unsubscribed
invalidToken
missingRequirement
invalidContact
billingIssue
unknownError
incorrectPhoneNumber
creditLimitReached
invalidMessageText
{
  • "code": 1,
  • "message": "The request succeeded",
  • "smsid": "5bec5b9d0a975a238808ffb2"
}

Send MMS message

Send a multimedia message to an individual contact. This function accepts POST requests only. Each outgoing MMS message is worth 3 credits.

Be sure to check what MMS filetypes are supported by your number. Note that some devices don't support PDF files via MMS.

If a contact is unable to receive MMS, they will receive a fallback message with a link instead. It reads as follows:

You were sent a message that contains rich media not supported by your carrier. See the full message here: [URL]

Visit this article to learn what carriers support MMS.

If the message contains a link from a common third-party link shortener such as bit.ly, it will appear from our URL shortener instead and occupy 20 characters. Learn more

Authorizations:
None
query Parameters
phone
required
string

10 digit phone number to send the message to

message
required
string

The body of your MMS (1600 characters maximum)

subject
string

The subject of your MMS (80 characters maximum).

mediaUrl
Array of strings <= 2 items

2 link maximum. The maximum total size is 1000KB. Images will be sent as is, without resizing.

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/sendmms?token=YOUR_API_TOKEN&phone=SOME_STRING_VALUE&message=SOME_STRING_VALUE&subject=SOME_STRING_VALUE&mediaUrl=SOME_ARRAY_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
unsubscribed
invalidToken
missingRequirement
invalidContact
billingIssue
unknownError
incorrectPhoneNumber
creditLimitReached
invalidMessageText
invalidSubjectText
invalidMediaType
mediaUnreachable
mediaSizeExceeded
tooManyLinks
{
  • "code": 1,
  • "message": "The request succeeded",
  • "smsid": "5bec5b9d0a975a238808ffb2"
}

Check remaining credits

Retrieve your remaining credit balance for the current billing cycle. Each outgoing SMS message is worth 1 credit. Each MMS outgoing message is worth 3 credits. Incoming messages with media attached, such as photos, are considered MMS and worth 1 credit each. Incoming SMS are free! Unused credits roll over. Learn more

Authorizations:
None
header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/messaging/check?token=YOUR_API_TOKEN");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
{
  • "code": 1,
  • "message": "The request succeeded",
  • "messagesCount": 2989
}

List all sent campaigns

Set a date range and view all the campaigns sent in that period. Messages sent from the Inbox will not appear in this query.

Authorizations:
None
query Parameters
datefrom
string

Date from (Format: YYYY-MM-DD)

dateto
string

Date to (Format: YYYY-MM-DD)

date
string

Date (Format: YYYY-MM-DD)

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/messaging/sent/list?token=YOUR_API_TOKEN&datefrom=SOME_STRING_VALUE&dateto=SOME_STRING_VALUE&date=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
invalidDate
{
  • "code": 1,
  • "message": "The request succeeded",
  • "list": [
    ]
}

List all scheduled campaigns

SimpleTexting allows you to schedule messages for a specific time and date in the future. Use this function to view all upcoming, scheduled campaigns.

Authorizations:
None
header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/messaging/scheduled/list?token=YOUR_API_TOKEN");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
{
  • "code": 1,
  • "messages": "The request succeeded",
  • "list": [
    ]
}

Show campaign info

Returns the campaign’s message, send date, and how many subscribers it sent to. If the campaign is an MMS message this call will also return its subject.

Authorizations:
None
query Parameters
id
required
string

The campaign id

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/messaging/message?token=YOUR_API_TOKEN&id=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
invalidCampaign
{
  • "code": 1,
  • "message": "The request succeeded",
  • "list": [
    ]
}

Remove a campaign

Delete a campaign from your account.

Authorizations:
None
query Parameters
id
required
string

The campaign ID

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/messaging/delete?token=YOUR_API_TOKEN&id=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
invalidCampaign
{
  • "code": 1,
  • "message": "The request succeeded"
}

Contacts

At a minimum, each contact in SimpleTexting must have a phone number. Contacts can also hold additional information including first name, last name, and email address. You can also create custom fields to store data specific to your website or app’s needs.

List all contacts

List all contacts

Authorizations:
None
query Parameters
group
required
string

The list name

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/group/contact/list?token=YOUR_API_TOKEN&group=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
unknownError
invalidListName
{
  • "code": 1,
  • "message": "The request succeeded",
  • "contacts": [
    ]
}

Add contact to list

Add contact to list

Authorizations:
None
query Parameters
group
required
string

The list name

phone
required
string

Phone number

firstName
string

Contact's first name

lastName
string

Contact's last name

email
string

Contact's email

comment
string

Notes about contact

birthday
string

Contact's birthday in format (mm/dd/yyyy)

customField
string

Any custom field of a contact, where customField` must be replaced with the actual custom field’s parameter.

For example, if you have a ‘Street address’ custom field, you would use the parameter ‘street_address’.

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/group/contact/add?token=YOUR_API_TOKEN&group=SOME_STRING_VALUE&phone=SOME_STRING_VALUE&firstName=SOME_STRING_VALUE&lastName=SOME_STRING_VALUE&email=SOME_STRING_VALUE&comment=SOME_STRING_VALUE&birthday=SOME_STRING_VALUE&customField=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
invalidCustomField
billingIssue
unknownError
invalidEmail
invalidListName
contactError
invalidContactPhone
alreadyAdded
importLimitExceeded
duplicateContact
unknownCustomField
{
  • "code": 1,
  • "message": "The request succeeded"
}

Update a contact

Update a contact’s phone number or any other field.

Authorizations:
None
query Parameters
group
required
string

The list name

phone
required
string

Phone number

firstName
string

Contact's first name

lastName
string

Contact's last name

email
string

Contact's email

comment
string

Notes about contact

birthday
string

Contact's birthday in format (mm/dd/yyyy)

customField
string

Any custom field of a contact, where customField must be replaced with the actual custom field’s parameter. For example, if you have a Street address custom field, you would use the parameter street_address.

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/group/contact/update?token=YOUR_API_TOKEN&group=SOME_STRING_VALUE&phone=SOME_STRING_VALUE&firstName=SOME_STRING_VALUE&lastName=SOME_STRING_VALUE&email=SOME_STRING_VALUE&comment=SOME_STRING_VALUE&birthday=SOME_STRING_VALUE&customField=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
invalidCustomField
billingIssue
unknownError
invalidEmail
invalidListName
invalidContactPhone
duplicateContact
unknownCustomField
contactDoesntExist
{
  • "code": 1,
  • "message": "The request succeeded"
}

Remove a contact from list

Remove a contact from a specific. If you don’t specify a list, the contact will be removed from all lists.

Authorizations:
None
query Parameters
phone
required
string

The phone number of the contact to be removed

group
string

List name

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/group/contact/remove?token=YOUR_API_TOKEN&phone=SOME_STRING_VALUE&group=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
invalidListName
notRemoved
invalidNumberPassed
{
  • "code": 1,
  • "message": "The request succeeded"
}

Add a contact to the unsubscribed contacts list

Add a contact to the unsubscribed contacts list. These contacts will no longer receive messages from you unless you remove them from the list.

Authorizations:
None
query Parameters
phone
required
string

The phone number of the contact to be removed

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/contacts/blocklist/add?token=YOUR_API_TOKEN&phone=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
invalidContactPhone
importLimitExceeded
{
  • "code": 1,
  • "message": "The request succeeded"
}

Remove a contact from the unsubscribed contacts list

Remove a contact from the unsubscribed contacts list. Contacts can also manually resubscribe by replying “UNSTOP” to your number.

Authorizations:
None
query Parameters
phone
required
string

The phone number of the contact to be removed

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/contacts/blocklist/remove?token=YOUR_API_TOKEN&phone=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
invalidContactPhone
contactNotUnsubscribed
{
  • "code": 1,
  • "message": "The request succeeded"
}

Keywords

A keyword is a word or phrase that people can text to your number to subscriber to future messages. All SimpleTexting accounts come with unlimited keywords.

Check if a keyword is available

Find out if a keyword is available on your number. If you have a dedicated number, you can create any keyword you’d like, as long as it’s not a system keyword such as STOP or HELP. On shared short code, you may find that certain keywords are already taken by other clients.

Authorizations:
None
query Parameters
keyword
required
string

The keyword to be checked

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/keyword/check?token=YOUR_API_TOKEN&keyword=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
keywordAvailable
keywordAvailable
keywordUnavailable
invalidToken
missingRequirement
billingIssue
unknownError
{
  • "code": 1,
  • "message": "The keyword is available"
}

Rent an available keyword

Set up a keyword on the number associated with your account. Learn more about the number options available to you.

Authorizations:
None
query Parameters
keyword
required
string

The keyword to be rented

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/keyword/rent?token=YOUR_API_TOKEN&keyword=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
invalidNewKeyword
keywordLimitReached
{
  • "code": 1,
  • "message": "The request succeeded"
}

Configure settings for a keyword

Add a custom autoreply to a keyword on your account. You can also add an email to which you can forward new opt-ins.

Authorizations:
None
query Parameters
keyword
required
string

The keyword to be configured

autoreply
string

Customers that text the keyword to your number will receive this message upon subscription. If you do not update this field, we will send out our default autoreply: Thank you for joining our list.

optinsemail
string

Email for opt-ins forwarding

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/keyword/configure?token=YOUR_API_TOKEN&keyword=SOME_STRING_VALUE&autoreply=SOME_STRING_VALUE&optinsemail=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
invalidOptionalParameter
billingIssue
unknownError
keywordDoesNotExist
invalidAutoReply
invalidOptins
{
  • "code": 1,
  • "message": "The request succeeded"
}

Remove a keyword

Remove a keyword from your account. Contacts will no longer be able to text in this keyword to join your list.

Authorizations:
None
query Parameters
keyword
required
string

The keyword to be removed

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"
Content-Type
required
string
Value: "application/x-www-form-urlencoded"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/keyword/remove?token=YOUR_API_TOKEN&keyword=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
headers = curl_slist_append(headers, "content-type: application/x-www-form-urlencoded");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
keywordDoesNotExist
{
  • "code": 1,
  • "message": "The request succeeded"
}

List all keywords

List all the keywords currently set up on your account.

Authorizations:
None
header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/keyword/list?token=YOUR_API_TOKEN");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
billingIssue
unknownError
{
  • "code": 1,
  • "message": "The request succeeded",
  • "list": [
    ]
}

Analytics

Autoresponders are messages that go out a set period of time after a contact joins your list. Use the calls below to find out more about your autoresponders. For other analytics info, log into your SimpleTexting account and visit the analytics section.

Export autoresponder analytics

Export your autoresponder analytics in JSON or XML format via our API. The report can be filtered by date range. Fields will appear in the same order they do in SimpleTexting under Analytics -> Messaging Report -> Autoresponders.

Authorizations:
None
query Parameters
datefrom
required
string

Analytics start date in YYYY-MM-DD format.

dateto
required
string

Analytics end date in YYYY-MM-DD format

header Parameters
Accept
required
string
Default: application/json
Enum: "application/json" "application/xml"

Responses

Request samples 

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://app2.simpletexting.com/v1/analytics/autoresponders?token=YOUR_API_TOKEN&datefrom=SOME_STRING_VALUE&dateto=SOME_STRING_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "accept: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
Example
success
success
invalidToken
missingRequirement
invalidAnalyticDate
invalidDateFormat
{
  • "code": 1,
  • "message": "The request succeeded",
  • "entities": [
    ]
}