Send Text Messages by API
Table of Contents
Overview / How it Works
|
1. Your server makes an HTTP request to a TextMarks API server.
2. TextMarks sends your text messages too all members of your group
or to individuals specified.
|
Getting Started
If you don't have an account yet, you can sign up for a free trial here.
TextMarks provides access to the shared shortcode 41411. Mobile phones can send to and receive text messages from shortcodes just like regular 7 or 10 digit phone numbers, but shortcodes are easier to remember and use.
All of your messaging must take place in the context of a keyword "group". To identify your group on our shared shortcode, register a keyword for your users to use when texting 41411. Your keyword is a bit like a domain name and should be short and meaningful. Some examples: JMCYOUTH, DALIS, KERNSON4TH, MRJONESP4... (You would tell people to "Text JMCYOUTH to 41411 to join our group")
To register your group keyword, make sure you're logged in to www.TextMarks.com. Then click the "Manage Keywords" tab, then click the orange "Create" button, type in your keyword, and assuming it's available, it's yours!
Next go to the Subscription Settings panel for your keyword:
Make sure "automatic" subscription is enabled so that anybody who texts your keyword to 41411 will be subscribed your group. You can also optionally set a welcome message on this page that new group members will receive. Try it yourself from your phone.
NOTE: To unsubscribe from all keywords, anybody can text the word "STOP" to 41411. You can also unsubscribe from a specific keyword by texting "UNSUB KEYWORD" to 41411.
NOTE: In addition to the welcome message, you can also enable an automatic response (in Settings / Automatic Response). This is useful if you have more information than can fit in the welcome message. Additionally you may wish to send a special message or offer to users as an incentive for joining ("opting in to") your group. If enabled (in Settings / Opt-in Offer), users will receive this special message ONLY the first time they opt in, unlike the welcome message which would be received again if a user opts out and in again.
Building your Subscriber List
Unlike simpler text message gateways, TextMarks offers fully carrier compliant group management features that allow you to focus on your application itself instead of worrying about complex regulations and building your own opt-in and opt-out pathways. And because TextMarks takes SPAM seriously, you and your users can feel comfortable using your SMS service without worrying about numbers being sold or misused. Once your users join your keyword group, you're free to message any or all of them any time you want, safely and securely.
The best ways to add your users as potential text recipients:
- Tell users to "Text KEYWORD to 41411".
- Users can subscribe from your own site via one of our customizable HTML widgets.
- From your own website or app, invoke our Anybody.invite_to_group API call.
- See other options in the "Promotion Tools" menu for your keyword.
You may view and manage your current subscribers and see historical graphs of subscriber growth in the Reports menu for your keyword under "Subscribers" and "Analytics" respectively:
NOTE: If you want to keep a list of subscribers on your own servers in sync with the active list, consider enabling the "Sub Callback" under your keyword's API settings. This will trigger an HTTP request to a URL you provide every time a user opts in or out of your keyword list.
Relevant API Functions
Using the TextMarks SMS API, you can easily send text messages to a single member of your group or all members of your group. The API package GroupLeader contains both of the methods you might be interested in:
- GroupLeader.broadcast_message - to send the same text message to all members of your keyword group.
- GroupLeader.send_one_message - to send a single text message to one member of your keyword group.
In the next section we'll cover how to actually invoke these API functions.
NOTE: To send messages to a subset of your group, you may call send_one_message for each individual user. However if you know up front that you will be frequently messaging the same subsets, consider registering 2 or more keywords to allow your users to partition themselves and then using broadcast_message for each keyword.
Install a Client Library
Client libraries for the TextMarks API are available in many popular languages below. Because the protocol is based on simple HTTP interactions, you should be able to easily write your own integration in any other language as well. Feel free to contact developer support with questions.
PHP
Download: TextMarks-APIClient-PHP.zip - ~4 KB
Support Files (required ONLY for PHP 5.1 or older): JSON.php - ~34 KB
Example code: (click to show)
Python
Download: TextMarks-APIClient-Python.zip ~3 KB
Support Files (required ONLY for Python 2.5 or older): simplejson - (JSON support for Python 2.5 or older)
Example code: (click to show)
Java
Download: TextMarks-APIClient-Java.zip - ~72 KB
Example code: (click to show)
.NET
Download: TextMarks-APIClient-DotNet.zip - ~340 KB
To use this .NET API client, you may extract the ZIP file and then choose any of these approaches:
- You may copy the pre-built .DLLs from the TextMarksV2APIClient-DotNet/bin/Release/ directory into your own project.
- You may use the API client source directly in your project.
- You may build the DLLs yourself and include these in your own project.
Example code: (click to show)
Error Handling
All TextMarks API function calls return a numeric result code ("rescode"), with 0 (zero) indicating success. Any non-zero (error) condition is typically accompanied by a result message ("resmsg"). Each client library will handle these errors differently, for example by raising/throwing exceptions. Some client libraries further differentiate between transport exceptions (such as due to network connectivity issues) and result exceptions (such as due to invalid parameters specified).
For information about which specific error cases you should check for, see the API function reference for each specific function you are calling. The full list of error codes is available here:
Ready to start?
Sign up today for a free trial and experience the power and simplicity of the best text message API you'll find.
