![](\"https://assets.postman.com/postman-docs/accessing-saved-examples.jpg\")
With so many SMS APIs on the market today, you might think that they all do the same thing: send text messages. But with our flexible and powerful suite of APIs, you can do more than that.
\nWith our SMS messaging REST API you can:
\n* Send SMS messages
* Format numbers for SMS delivery
* Retrieve information about messages and campaigns sent
* Add and remove contacts
* Unsubscribe contacts
* Authorise email SMS accounts
* Retrieve account balance
* Lease virtual numbers and set options.
* Receive real time delivery reports (DLR) for all messages sent via callback
* Receive replies and inbound SMS messages via polling or callback
* Process link hits via polling or callback
* Setup, activate and deactivate keyword campaigns
The easiest way to start using the Transmit SMS API is by clicking the Run in Postman button above.
\n\nis a free tool which helps developers run and debug API requests, and is the source of truth for this documentation.
\nEvery endpoint you see documented here is readily available by running our Postman collection. Import the collection directly into the Postman app and access all saved examples from \"Examples\" dropdown in the upper right corner of the builder.
\n
* Avoid excessive polling. If you are making a lot of GET requests consider using a callback instead.
* Understand rate limits. Default is 15 calls per second. This can be increased by request.
MMS: https://api.transmitmessage.com\nAll other calls: https://api.transmitsms.com\n\nAll API requests require your API credentials, you will find them once logged into your account on the SETTINGS page. Scroll down to API Settings to find your API key and set your API secret.
\nYour API Secret can be anything you like. Think of the API Secret as a password field where you will need to enter an alphanumeric of your choice. Once you enter your chosen API Secret, click on the UPDATE PROFILE button to save your settings.
\n![](\"https://res.cloudinary.com/burst/image/upload/v1594795887/FyMeLX68fF7Q_fjtbi1.png\")
For security purposes, API credentials must be passed as HTTP Basic Authentication headers not as CGI parameters. Enter your API key and API secret in the Username and Password fields:
\n![](\"https://assets.postman.com/postman-docs/basic-auth.jpg\")
If an API Key is missing, malformed, or invalid, you will receive a 401 Unauthorised response code and the following JSON response:
{\n \"error\": {\n \"code\": \"AUTH_FAILED\",\n \"description\": \"The auth data you have provided is invalid.\"\n }\n}\n\nAll requests must be to the base URL. We provide you with an option of a response as a JSON object, or an XML string. You can choose which response you want by selecting the appropriate suffix (.json OR .xml) in your request. You can find both JSON and XML in code examples for each endpoint.
\nAll requests are submitted through the HTTP POST or GET method using UTF-8 encoding and URL encoded values.
\nTo ensure security & privacy the API only works over HTTPS protocol for all requests. Also, for your own security, If you have a website with a form which sends SMS, be sure to send the request from your server and not directly from the browser. Otherwise, you could be giving away your API secret.
\nTo provide the best service to all our customers we limit the number of API calls which can be made by each account to 15 calls per sec. For heavy users we can increase your throttling speed, but please contact us to discuss your requirements.
\nIf you exceed this limit we will return two indicators which you can use in your code to detect that you have been throttled.
\nThe first is the HTTP status code 429 \"Too Many Requests\", the second is the error code \"OVER_LIMIT\" in the error block of the response body.
\nIf this happens message requests will be dropped, they will not be retried.
\nAll timestamps are in ISO8601 format, e.g. YYYY-MM-DD HH:MM:SS. The timezone is always UTC.
\nYou can elect to return a JSON or XML response by adding the appropriate extension to the base url. An extension must be provided otherwise a 404 Page Not Found will be returned.
\nhttps://api.transmitsms.com/send-sms.json\nhttps://api.transmitsms.com/send-sms.xml\n\nSome responses are too large to be returned in one go so we paginate. To identify which calls use pagination look for the \"page\" and \"max\" parameters in the parameter descriptions for each API call.
\nThese calls include a \"page\" block in the response with two values, \"count\" and \"number\". Count tells you how many pages are available and number indicates the page number you are on.
\n{\n \"page\":{\n \"count\":1,\n \"number\":1\n }\n}\n\nThe page parameter is used to request a certain page, it defaults to 1. The max parameter is used to limit the number of results returned per page, the default is 10, the maximum is 100.
\nAlways check if your API call was successful or resulted in error. You may check the following
\n* 200 OK response header.
* 4XX ERROR response header
Please check the table below for common error constants. Note that some API functions can return custom errors of their own (listed in appropriate document sections). Check the error description for details, e.g. which field caused an error or which resource you don’t have access to.
\n| CODE | HEADER | DESCRIPTION |
|---|---|---|
SUCCESS | 200 | OK |
AUTH_FAILED_NO_DATA | 401 | You have not provided auth data. |
AUTH_FAILED | 401 | The auth data you have provided is invalid. |
NOT_IMPLEMENTED | 404 | The method you are requesting is unsupported. |
OVER_LIMIT | 429 | You have exceeded the request limit. |
FIELD_EMPTY | 400 | Required field is empty. |
FIELD_INVALID | 400 | Field has invalid format (see proper format in the description). |
NO_ACCESS | 400 | You don't have access to this feature |
KEY_EXISTS | 400 | The resource with this key already exists. |
LEDGER_ERROR | 400 | Insufficient funds to carry out debit |
BAD_CALLER_ID | 400 | The sender ID you have set is not valid or number is inactive or expired |
Thanks for taking the time to try our API. transmitsms.com has a very stable and robust enterprise level API infrastructure.
\nIf there is a known issue with our servers it will be announced in real time at:
\n\nand
\n\nIf a transmitsms.com outage is not the cause of your connection problem or you are having any other type of issue please consider the following information.
\nWhile our developers love to help out our clients, they are very busy and it can take some time to get a response from the team.
\nOur API is very generic and therefore has many solutions and environments targeting it with many potential issues that may be affecting your connection.
\nYou will find it much quicker to troubleshoot the problem yourself and we have produced this guide to help you do just that.
\nTo troubleshoot your connection you should be prepared to use Google. By Googling error codes or common terms like \"HTTP API connection\" you should be able to find information on websites like Stack Overflow to help you
\n\nConsider checking your network topology, look at firewalls, load balancers and other network areas that maybe causing your server to not be able to connect.
\nMost HTTP connection errors are caused by basic issues like incorrectly used auth or incorrectly formatted URLS.
\nYou should be familiar with the HTTP protocol.
\nHow To Use Traceroute and MTR to Diagnose Network Issues
\nwww.digitalocean.com/community/tutorials/how-to-use-traceroute-and-mtr-to-diagnose-network-issues
\n10 tips for troubleshooting DNS problems
\nwww.techrepublic.com/blog/10-things/10-tips-for-troubleshooting-dns-problems
\nTroubleshooting proxy firewall connections
\nsearchsecurity.techtarget.com/tip/Troubleshooting-proxy-firewall-connections
\nDiagnosing DNS resolution problems
\ndevelopers.google.com/speed/public-dns/docs/troubleshooting
\n8 Linux Nslookup Commands to Troubleshoot DNS (Domain Name Server)
\nwww.tecmint.com/8-linux-nslookup-commands-to-troubleshoot-dns-domain-name-server
\nIf you are an expert in diagnosing HTTP API connection problems, have scoured your code for that extra & symbol that shouldn't be there or have any kind of problem that cannot be easily diagnosed. We can assist but you must provide ALL of the following information
\nAPI method being used?
\ni.e. send-sms
\nLanguage being used?
\ni.e. php, .Net
\nAre you using the relevant library?
\nY/N
\nIf you are using .NET have you tried the example app with your own API details and did it work?
\nY/N
\nWhat are you trying to achieve with the API?
\ni.e. I'm trying to send an sms message to 12 recipients
\nWhat error are you getting from the API? Textual description given in the response.
\ni.e. ‘Not Authorised’
\nNB: WE MUST HAVE A HTTP REQUEST/RESPONSE CAPTURE (Without this we cannot help you)
\nIf using one of the libraries please provide a capture of the HTTP Requests and Responses sent and received by the API. We recommend this tool for capturing the API calls:
\nhttp://www.telerik.com/fiddler
\nPlease provide the output of attempting the relevant API command call with curl, as provided on the API methods documentation page.
\nIf possible/comfortable, please provide a copy of or access to the relevant source code for your project.
\nThe best way to get immediate notification on the events like SMS delivery or incoming messages, is to set up callback URLs. We will notify this URL immediately after the event occurs and, if the call was unsuccessful, we will retry a few times later. We perform a GET request.
\nNB: If you need to pass a predefined parameter, you can include it in your URL.
\nCallbacks can be set in several different places within your account.
\nWhich callback URL is notified is prioritised as follows. Duplicate callbacks will not be sent.
\nIf you are finding that a callback is not firing from SETTINGS or a Forward to URL. It is likely you have one set on the send-sms call.
\nIf we should not be able to reach your configured http callback endpoint, we will retry the attempt a maximum of 4 times with an increasing delay of 1 minute, 5 minute, 1 hour and finally 24 hours.
\nDLR's or Delivery Receipts, are notifications received from the carriers relating to the success or otherwise of an attempted SMS Delivery. Your DLR Callback URL is the default URL we post incoming DLR's to. You can also set the DLR Callback URL separately for individual messages. This is done using a parameter on the send-sms call.
\nParameters we include in our delivery callback request:
\n| PARAMETER | DESCRIPTION | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
message_id | Your message ID | ||||||||||
mobile | Recipient mobile number | ||||||||||
datetime | Date/time of delivery. UTC. | ||||||||||
status |
| ||||||||||
user_id | Your account ID |
Example
\nhttps://www.myserver.com/processdlr.php?myparameter=myvalue&message_id=331694668&mobile=61438333061&datetime=2020-05-16 12:10:00&status=delivered&user_id=123456\n\nIncoming SMS are broadly similar, with 2 subtly different forms:
\n* SMS Replies: are messages received 'in response' to an SMS message sent by you. Responses can come in on both the System Shared Number Pool or any Dedicated Virtual Number, and will be posted to the Callback URL above if there was no URL set as a parameter in the send-sms call.
* Inbound SMS: are messages that are received originating from a users mobile phone and are not in response to a message sent. Inbound SMS can only be received on a Dedicated Virtual Number and will only be posted to the Default URL supplied above.
Parameters we include in our reply callback request:
\n| PARAMETER | DESCRIPTION |
|---|---|
user_id | Your account ID |
message_id | Your message ID |
mobile | Sender’s mobile |
longcode | The virtual number message was sent to |
datetime_entry | Date/time that message was received. UTC |
response | Message text |
response_id | ID assigned to incoming message |
is_optout | Opt-out flag. ‘yes’ or ‘no’ |
Example
\nhttps://www.myserver.com/processreply.php?myparameter=myvalue&user_id=54911&message_id=331695745&&response=This is my reply&response_id=35566670&mobile=61438333061&longcode=61429997672&datetime_entry=2020-05-16 12:10:00&is_optout=no\n\nThe default link hits callback URL is used to notify when a tapth.is/xxxxx URL defined in a message is clicked.
\nParameters we include in our link hits callback request:
\n| PARAMETER | DESCRIPTION |
|---|---|
list_id | Your list ID |
message_id | Your message ID |
mobile | Sender’s mobile |
longcode | The number message was delivered to |
datetime | Date/time that the click was recorded |
message | Message text |
user_id | Account ID |
link_hits | Link hit count |
firstname | Firstname of contact that clicked |
lastname | Lastname of contact that clicked |
Example
\nhttps://www.myserver.com/processlinkhit.php?datetime=2020-05-16 13:23:46&firstname=Brad&lastname=Down&link_hits=1&list_id=3201749&longcode=TRANSMITSMS&message=This is a link hit callback test\n TapTh.is/clkVMt8z \nUnsubRep.ly/3hHm1u8u&message_id=331696764&mobile=61438333061&rate=10&user_id=54911\n\nA notification for contacts added too, or removed from lists is available via the Forward to URL option in the AUTOMATION settings for a list.
\nParameters we include in our list action callback request:
\n| PARAMETER | DESCRIPTION |
|---|---|
type | Add or Delete |
datetime_entry | Date/time of action. UTC. |
list_id | ID of list. |
mobile | Mobile of number actioned |
firstname | Firstname of contact |
lastname | Lastname of contact |
Custom field 1-10 | Custom field names and values will be added also |
Example
\nhttps://www.myserver.com/processdlr.php?Carrier=Telstra&Email=harrisondown06@gmail.com&Handset=iPhone 7&datetime_entry=2020-05-16 13:13:20&firstname=Harrison&lastname=Down&list_id=4026600&mobile=61447775960&type=delete\n\nIn its most simple form the send-sms API call can send the message and set a callback to receive a reply to your application using a single command.
\n","urlObject":{"protocol":"https","path":["send-sms.json"],"host":["api","transmitsms","com"],"query":[],"variable":[]}},"response":[{"id":"dc37e202-59b7-4778-827b-25ac4835a8f6","name":"Example ","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.transmitsms.com/send-sms.json?message=Hi {myvariable}, this is my message&reply_callback=https://www.myserver.com/processreply.php?myparameter=myvalue&to=1234567890","protocol":"https","host":["api","transmitsms","com"],"path":["send-sms.json"],"query":[{"key":"message","value":"Hi {myvariable}, this is my message"},{"key":"reply_callback","value":"https://www.myserver.com/processreply.php?myparameter=myvalue"},{"key":"to","value":"1234567890"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 21 Jun 2020 04:47:25 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx/1.14.2"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"X-Mashape-Billing","value":"Queries=1; Messages=1"},{"key":"Content-Encoding","value":"gzip"},{"key":"Vary","value":"Accept-Encoding"}],"cookie":[],"responseTime":null,"body":"{\n \"message_id\": 340263609,\n \"send_at\": \"2020-06-21 04:47:25\",\n \"recipients\": 1,\n \"cost\": 0.087,\n \"sms\": 1,\n \"delivery_stats\": {\n \"delivered\": 0,\n \"pending\": 0,\n \"bounced\": 0,\n \"responses\": 0,\n \"optouts\": 0\n },\n \"error\": {\n \"code\": \"SUCCESS\",\n \"description\": \"OK\"\n }\n}"}],"_postman_id":"3bea37a5-490d-4a78-bb29-854b165478a1"},{"name":"Add list and upload","id":"f28eda42-b960-4c90-9766-476bba383601","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.transmitsms.com/add-contacts-bulk.json","description":"Single SMS sends are limited to 15 calls per second. The best way to process large volumes of messages is to add contacts to a list and then send as a campaign.
\nUse the add-contacts-bulk call to create a list, custom fields and upload your file in a single call.
\n","urlObject":{"protocol":"https","path":["add-contacts-bulk.json"],"host":["api","transmitsms","com"],"query":[],"variable":[]}},"response":[{"id":"6cb68a49-0729-423a-9145-82ff4be6ad59","name":"Example","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.transmitsms.com/add-contacts-bulk.json?name=My Large Customer List&field_1=Postcode&field_2=Email&file_url=https://www.myserver.com/mylist.csv","protocol":"https","host":["api","transmitsms","com"],"path":["add-contacts-bulk.json"],"query":[{"key":"name","value":"My Large Customer List"},{"key":"field_1","value":"Postcode"},{"key":"field_2","value":"Email"},{"key":"file_url","value":"https://www.myserver.com/mylist.csv"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 21 Jun 2020 05:22:18 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx/1.14.2"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"X-Mashape-Billing","value":"Queries=1"},{"key":"Content-Encoding","value":"gzip"},{"key":"Vary","value":"Accept-Encoding"}],"cookie":[],"responseTime":null,"body":"{\n \"list_id\": 4200327,\n \"error\": {\n \"code\": \"SUCCESS\",\n \"description\": \"OK\"\n }\n}"}],"_postman_id":"f28eda42-b960-4c90-9766-476bba383601"},{"name":"Send campaign to list","id":"4b63a4bf-aea9-4cad-93d3-7f2df058402a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.transmitsms.com/send-sms.json","description":"Use the send-sms call, however instead of setting the to parameter use the list id that was returned in the response of the add-contacts-bulk call above.
\n","urlObject":{"protocol":"https","path":["send-sms.json"],"host":["api","transmitsms","com"],"query":[],"variable":[]}},"response":[{"id":"0bcbf6f6-8b56-4742-b998-a890edcf519f","name":"Example","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.transmitsms.com/send-sms.json?message=Hi [firstname], this is my message&reply_callback=https://www.myserver.com/processreply.php?myparameter=myvalue&list_id=4070887","protocol":"https","host":["api","transmitsms","com"],"path":["send-sms.json"],"query":[{"key":"message","value":"Hi [firstname], this is my message"},{"key":"reply_callback","value":"https://www.myserver.com/processreply.php?myparameter=myvalue"},{"key":"list_id","value":"4070887"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 21 Jun 2020 05:25:59 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx/1.14.2"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"X-Mashape-Billing","value":"Queries=1; Messages=1"},{"key":"Content-Encoding","value":"gzip"},{"key":"Vary","value":"Accept-Encoding"}],"cookie":[],"responseTime":null,"body":"{\n \"message_id\": 340267059,\n \"send_at\": \"2020-06-21 05:25:59\",\n \"recipients\": 1,\n \"cost\": 0.087,\n \"sms\": 1,\n \"list\": {\n \"id\": 4070887,\n \"name\": \"My Test List\"\n },\n \"delivery_stats\": {\n \"delivered\": 0,\n \"pending\": 0,\n \"bounced\": 0,\n \"responses\": 0,\n \"optouts\": 0\n },\n \"error\": {\n \"code\": \"SUCCESS\",\n \"description\": \"OK\"\n }\n}"}],"_postman_id":"4b63a4bf-aea9-4cad-93d3-7f2df058402a"},{"name":"Delivery Receipt","id":"d06c3aa5-f653-4621-8360-423731404687","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[],"url":"https://api.transmitsms.com/send-sms.json","description":"DLR's or Delivery Receipts, are notifications received from the carriers relating to the success or otherwise of an attempted SMS Delivery. Your DLR Callback URL is the default URL we post incoming DLR's to. You can also set the DLR Callback URL separately for individual messages. This is done using a parameter on the send-sms call.
\nThere are 4 different API calls that can be used to retrieve information about messages sent from the system. They differ slightly depending on the complexity of the solution you are trying to develop and the choice is one of features vs. performance.
\nThe following table lists the responses that each call returns use this to figure out what level of reporting you need.
\n","urlObject":{"protocol":"https","path":["send-sms.json"],"host":["api","transmitsms","com"],"query":[],"variable":[]}},"response":[{"id":"a6d28fd6-0eec-4e1f-b5dc-fcbabca11c77","name":"Example ","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.transmitsms.com/send-sms.json?message=Hi {myvariable}, this is my message&dlr_callback=https://www.myserver.com/processdlr.php?myparameter=myvalue&to=1234567890","protocol":"https","host":["api","transmitsms","com"],"path":["send-sms.json"],"query":[{"key":"message","value":"Hi {myvariable}, this is my message"},{"key":"dlr_callback","value":"https://www.myserver.com/processdlr.php?myparameter=myvalue"},{"key":"to","value":"1234567890"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 21 Jun 2020 04:47:25 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx/1.14.2"},{"key":"Expires","value":"Thu, 19 Nov 1981 08:52:00 GMT"},{"key":"Cache-Control","value":"no-store, no-cache, must-revalidate"},{"key":"Pragma","value":"no-cache"},{"key":"X-Mashape-Billing","value":"Queries=1; Messages=1"},{"key":"Content-Encoding","value":"gzip"},{"key":"Vary","value":"Accept-Encoding"}],"cookie":[],"responseTime":null,"body":"{\n \"message_id\": 340263609,\n \"send_at\": \"2020-06-21 04:47:25\",\n \"recipients\": 1,\n \"cost\": 0.087,\n \"sms\": 1,\n \"delivery_stats\": {\n \"delivered\": 0,\n \"pending\": 0,\n \"bounced\": 0,\n \"responses\": 0,\n \"optouts\": 0\n },\n \"error\": {\n \"code\": \"SUCCESS\",\n \"description\": \"OK\"\n }\n}"}],"_postman_id":"d06c3aa5-f653-4621-8360-423731404687"}],"id":"1777c857-7342-4669-bc4a-7a288da14973","description":"Our simple REST API allows you to get up and running in minutes, with just a single line of code. For advanced users, dig deeper into our technology and check our reference guides for more detailed functions and calls. We also offer a number of client libraries and code samples in order to make your experience using the API suite as easy and intuitive as possible.
\n","event":[{"listen":"prerequest","script":{"id":"94b1ab0a-594d-4a4d-86c7-1164441279a6","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"c10ca520-b49c-444a-b710-77376530e5bc","type":"text/javascript","exec":[""]}}],"_postman_id":"1777c857-7342-4669-bc4a-7a288da14973"},{"name":"SMS","item":[{"name":"Send SMS","id":"74911cf8-dec6-4319-a499-7f535a7fd08c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[],"url":"https://api.transmitsms.com/send-sms.json","description":"You can elect to pass us the recipient numbers from your database each time you make a call, or you can elect to store recipient data in a contact list and submit only the list_id to trigger the send. This is best for large databases. To add a list please refer to the add-list call.
\n| KEY | TYPE | DESCRIPTION | REQUIRED | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
message | string | Message Content Can be up to 612 alphanumeric characters. A part is 160 characters for a single SMS or 153 characters per part for multi-part SMS. If the message contains Unicode UTF8 encoded characters such as emoji’s or non latin character sets, then a single part is 70 characters or 67 characters for multiple parts. More information on message length and encoding: | YES | ||||||||||||||||||||
to | string | Recipient Number/s Single number or set of up to 500 comma separated numbers to send the SMS to. Invalid numbers will be ignored. Number must be defined in E.164 international format. You can use countrycode parameter to format numbers that are in local format. | If list_id not set | ||||||||||||||||||||
list_id | integer | Recipient list This ID is the numerical reference to one of your recipient lists. It is found in the URL and displayed on a destination list page in your account. A list ID can also be created using the add-list call. | If to not set | ||||||||||||||||||||
countrycode | string | Format the to number in international format. 2 letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery. eg. In Australia 0422222222 will become 6142222222 when set to AU or Australia. If not set to numbers must be defined in E.164 international format.
| NO | ||||||||||||||||||||
from | string | Sender ID Usually a dedicated virtual mobile number (VMN) or short code found in the NUMBERS section of your account. If no value is set here, it will default to the shared Sender ID for the country you are sending to. Can also be an 11 character alphanumeric sender if available for the destination country. You will need to click on the Add Sender ID button found in the NUMBERS section of your account in order to request the use of an Alphanumeric Sender ID.
Mobile and dedicated VMN's should be in international format. Alphanumeric senders (cannot be replied to) can have a maximum of 11 characters. No spaces. If opt out is required, using Custom Sender ID, use parameter [unsub-reply-link] in message to insert opt out link. | NO | ||||||||||||||||||||
send_at | datetime | Schedule a message at a specific time. Must be in ISO8601 format YYYY-MM-DD HH:MM:SS utilising UTC Timezone. Eg. 2020-04-27 06:00:00 | NO | ||||||||||||||||||||
validity | integer | Expire a message send if it is undeliverable Specify the maximum time to attempt to deliver. In minutes, 0 (zero) or not set implies maximum validity period. If a message is not delivered and not failed it is given a PENDING status in the system. These messages can be requested to be expired by the carrier after a certain time. This will return a DLR with a soft-bounce value. If no value is set, messages that remain in a PENDING state will be expired by the system automatically after 72hrs. | NO | ||||||||||||||||||||
replies_to_email | string | Send Replies to this Email Specify an email address to send responses to this message. Email will come from the email address @transmitsms.com eg. 0456789010@transmitsms.com NOTE: If expectation is for replies to this email to be returned to the recipient as SMS then the email address must be authorised to send messages in your account under the 'EMAIL SMS' section. Emails can also be authorised using the add-email call. | NO | ||||||||||||||||||||
tracked_link_url | url | Converts this URL into a unique shortened tracking link Converts this URL to unique tapth.is/xxxxxx tracking link for each contact. Inserted into message with variable [tracked-link]. Only one [tracked-link] can be defined per message. | NO | ||||||||||||||||||||
link_hits_callback | url | Send a link hit notification to this callback URL A URL on your system which we can call to notify you of a hit on your [tracked-link]. If required, this parameter can be different for each message sent. Will override the default DLR Callback URL if set in the SETTINGS section of your account. | NO | ||||||||||||||||||||
dlr_callback | url | Send a delivery notification to this callback URL A URL on your system which we can call to notify you of Delivery Receipts. If required, this parameter can be different for each message sent. Will override the default DLR Callback URL if set in the SETTINGS section of your account. | NO | ||||||||||||||||||||
reply_callback | url | Send a reply notification to a callback URL A URL on your system which we can call to notify you of incoming messages. If required, this parameter can be different for each message sent. Will override the default Reply Callback URL if set in the SETTINGS section of your account. | NO |
| PARAMETER | DESCRIPTION | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
message_id | Numeric ID assigned to the message sent. This can be used in conjunction with other calls to retrieve information and reporting about the message sent. | ||||||||||||
send_at | Date and time that message was sent from your account Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||||||||||
recipients | Recipient count Count of number of recipients message was sent to either in list or to parameter. | ||||||||||||
cost | Total cost of all messages Returned as value per account currency to 3 decimal places 0.000 | ||||||||||||
sms | Total number of message parts delivered If the message is longer than 160 characters this will return count of all parts. Eg. if a 180 character message is delivered to 2 recipients. Value returned will be 4. | ||||||||||||
list | Information about the list the message was sent to
| ||||||||||||
delivery_stats | This response has been deprecated To retrieve live delivery stats use DLR callback or to poll for stats later use get-sms-delivery-status call. | ||||||||||||
error | Error messages related to this call, for general errors see the APIIntroduction
|
SUCCESS\n Messages scheduled can be cancelled using the message ID.
\nYou can elect to return a JSON or XML response by adding the appropriate extension to the base url (See examples).
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| id | integer | Numeric ID assigned to the message sent. This ID was returned in the send-sms response. | YES |
SUCCESS\n In the majority of cases, mobile phone number data coming from external systems is not ideal for SMS delivery. For highest reliability and to be able to route correctly a mobile number should be formatted in international format E.164
\nNormally however a number is stored in a CRM or contact database in local format, with spaces, hyphens and other types of unwanted characters that can cause a delivery to fail. The format-number call is used to sanitise a number by combining the country and the number. eg.
\n\n\nAustralia 0438 333 061 will become 61438333061
\n
\n\nNew Zealand 0212172782 will become 64212172782
\n
\n\nUSA (281) 869-1226 will become 12818691226
\n
| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| msisdn | integer | Numeric to check Badly formatted number coming from source such as CRM or exported list. | YES |
| countrycode | string | 2 letter ISO countrycode or country name Global SMS delivery list | YES |
| PARAMETER | DESCRIPTION | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| countrycode | International dialling code for destination country | ||||||||
| international | Reformatted number in international format | ||||||||
| isValid | Checks to see if number is valid Returns true or false. | ||||||||
| national_leading_zeroes | Unused, currently returns as per national_number | ||||||||
| national_number | Reformatted number without leading 0 | ||||||||
| rawinput | Unused, always returns null | ||||||||
| type | Returns numeric value depending on type of number
|
Responses to your outgoing messages can be picked up in a few different ways.
\nYour DLR Callback URL in your account settings, is the default URL we post incoming DLR's to. You can also set the DLR Callback URL separately for individual messages, using a parameter on the send-sms call. You can also poll the following endpoints for responses.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| message_id | integer | Numeric ID assigned to the message sent. This ID was returned in the send-sms response | If keyword_id or keyword not set |
| start | datetime | A date within the last 12 months to start the report from Must be in ISO8601 format YYYY-MM-DD HH:MM:SS utilising UTC Timezone. Eg. 2020-04-27 06:00:00 If start and end date not supplied will get everything from last 30 days only. | NO |
| end | datetime | A date within the last 12 months to end the report at Must be in ISO8601 format YYYY-MM-DD HH:MM:SS utilising UTC Timezone. Eg. 2020-04-27 06:00:00 If start and end date not supplied will get everything from last 30 days only. | NO |
| keyword_id | integer | Numeric ID assigned to the keyword. ID is assigned on creation of keyword in your account. A keyword can be created using add-keyword request. Keyword ID can be returned using the get-keyword request. NOTE: A keyword IS NOT a specific string within the message. | If message_id or keyword not set |
| keyword | string | Keyword name Name is assigned on creation of keyword in your account. A keyword can be created using add-keyword request. Keyword name can be returned using the get-keyword request. NOTE: A keyword IS NOT a specific string within the message. | If message_id or keyword_id not set |
| number | integer | Filter results by Virtual Mobile Number (VMN) Get responses for messages containing a keyword received on a specific VMN. Numbers can be returned using the get-numbers request. | If keyword is set |
| msisdn | integer | Filter results by Responder Mobile Number (VMN) Get responses to messages that were from a specific mobile number. | NO |
| include_original | boolean | Include text of message that reply was sent to | NO |
| page | integer | Page number, for pagination | NO |
| max | integer | Maximum results returned per page | NO |
SUCCESS\n | KEY | TYPE | DESCRIPTION | REQUIRED | ||||||
|---|---|---|---|---|---|---|---|---|---|
| start | datetime | A date within the last 12 months to start the report from If start and end date not supplied will get everything from last 30 days only. | NO | ||||||
| end | datetime | A date within the last 12 months to end the report at If start and end date not supplied will get everything from last 30 days only. | NO | ||||||
| keywords | boolean | Filter by keyword responses
| NO | ||||||
| include_original | boolean | Include text of message that reply was sent to Defaults to false if not supplied set to true to return. | NO | ||||||
| page | integer | Page number, for pagination | NO | ||||||
| max | integer | Maximum results returned per page | NO |
| PARAMETER | DESCRIPTION | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | Numeric ID assigned to the message received | ||||||||||||
| message_id | Numeric ID assigned to the message that was responded to | ||||||||||||
| list_id | Numeric ID of the list that the original message that sent to Returns 0 if message was not sent to a list. | ||||||||||||
| received_at | Date and time that response was received to your account Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||||||||||
| first_name | First name of responder Retrieved from list contact if available. | ||||||||||||
| last_name | Last name of responder Retrieved from list contact if available. | ||||||||||||
| msisdn | Mobile number of responder | ||||||||||||
| error | Error messages related to this call, for general errors see the API Introduction
|
SUCCESS\n The primary method of sending SMS
\n","event":[{"listen":"prerequest","script":{"id":"900025b7-b9d5-4ce7-a5a6-9b74a8e6fc69","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"aee61dde-59b4-4ec1-8396-93dac6e86e07","type":"text/javascript","exec":[""]}}],"_postman_id":"c23b71c1-a9b6-41c5-90cf-fca41f964f38"},{"name":"Reporting","item":[{"name":"Get Message/Campaign Information","id":"b4d6af58-03d0-467f-af0c-76fd66593178","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://api.transmitsms.com/get-sms.json","description":"This will return information about the campaign, including the message, list etc. It will not however return individual messages with populated variables or tracking links. To retrieve final individual messages use get-sms-delivery-status.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| message_id | integer | Numeric ID assigned to the message sent. This ID was returned in the send-sms response | YES |
| PARAMETER | DESCRIPTION | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| message_id | Numeric ID assigned to the message that was sent | ||||||||||||
| send_at | Date and time that message was sent from your account Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||||||||||
| recipients | Number of recipients message was sent to | ||||||||||||
| cost | Total cost of all messages Returned as value per account currency to 3 decimal places 0.000 | ||||||||||||
| sms | Total number of message parts delivered If the message is longer than 160 characters this will return count of all parts. Eg. if a 180 character message is delivered to 2 recipients. Value returned will be 4. | ||||||||||||
| message | Content of message sent | ||||||||||||
| list | ID and name of list delivered to | ||||||||||||
| delivery_stats | Report of messages delivered Count of different reporting stats we collect. Delivery reports are marked using a DLR (Delivery Receipt) or Acknowledgement (ACK) returned from the carrier, a DLR is a handset level report and an ACK is simply a response from the carrier that the request was received. Global carriers have different functionality available. See our Global Delivery List for details.
|
SUCCESS\n Retrieves detailed information about messages sent to a specific recipient. This included full message content including populated variables.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| message_id | integer | Numeric ID assigned to the message sent. This ID was returned in the send-sms response | YES |
| msisdn | integer | Mobile number of recipient | YES |
| PARAMETER | DESCRIPTION | ||||||
|---|---|---|---|---|---|---|---|
| message_id | Numeric ID assigned to the message that was sent | ||||||
| sender_id | Sender ID that message was sent from | ||||||
| mobile | Mobile number of recipient | ||||||
| send_at | Date and time that message was sent from your account Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||||
| datetime | Date and time that message was delivered This is the date returned in the DLR in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||||
| message | Content of message sent Includes populated variables | ||||||
| status | Report of message status Delivery reports are marked using a DLR (Delivery Receipt) or Acknowledgement (ACK) returned from the carrier, a DLR is a handset level report and an ACK is simply a response from the carrier that the request was received. Global carriers have different functionality available. See our Global Delivery List for details.
|
SUCCESS\n Retrieves total number of SMS sent in a given timeframe
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| start | datetime | A date to start the report from start and end date must be within 7 days \nIf start and end date not supplied will get everything from last 24 hrs only. | NO |
| end | datetime | A date to end the report at start and end date must be within 7 days \nIf start and end date not supplied will get everything from last 24 hrs only. | NO |
Retrieve information on messages sent during a period of time
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| start | datetime | A date to start the report from | YES |
| end | datetime | A date to end the report at | YES |
| msisdn | integer | Mobile number of contact being queried | NO |
| page | integer | Page number, for pagination | NO |
| max | integer | Maximum results returned per page | NO |
| response_style | string | response_style = 'array' returns custom field lists as an array | NO |
This will return paginated information regarding individual messages sent to provided mobile number.
\n| KEY | TYPE | DESCRIPTION | REQUIRED | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| mobile | integer | The mobile number of the recipient Number must be defined in E.164 international format. You can use countrycode parameter to format numbers that are in local format. | YES | ||||||||||||||||||||
| countrycode | string | Format the to number in international format. 2 letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery. eg. In Australia 0422222222 will become 6142222222 when set to AU or Australia. If not set to numbers must be defined in E.164 international format.
| NO | ||||||||||||||||||||
| start | datetime | Must be in ISO8601 format YYYY-MM-DD HH:MM:SS utilising UTC Timezone. Eg. 2020-04-27 06:00:00 If start and end date not supplied, will get everything from the account registration to current date. | NO | ||||||||||||||||||||
| end | datetime | Must be in ISO8601 format YYYY-MM-DD HH:MM:SS utilising UTC Timezone. Eg. 2020-04-27 06:00:00 If start and end date not supplied, will get everything from the account registration to current date. | NO | ||||||||||||||||||||
| sort_field | string | Sort by - delivery_status - message_id - datetime_send | NO | ||||||||||||||||||||
| order | string | Order by - asc - desc | NO | ||||||||||||||||||||
| page | integer | Page number, for pagination | NO | ||||||||||||||||||||
| max | integer | Maximum results returned per page | NO |
Count of different reporting stats we collect. Delivery reports are marked using a DLR (Delivery Receipt) or Acknowledgement (ACK) returned from the carrier, a DLR is a handset level report and an ACK is simply a response from the carrier that the request was received. Global carriers have different functionality available. See our Global Delivery List for details.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| message_id | integer | Numeric ID assigned to the message sent. This ID was returned in the send-sms response | YES |
| PARAMETER | DESCRIPTION |
|---|---|
| hard_bounced | Handset was disconnected |
| soft_bounced | Message was undeliverable Handset switched off, out of range or other temporary deliverability issue. |
| total | Number of messages sent |
| recipientCount | Number of recipients message was sent to |
| delivered | Messages delivered |
| pending | No delivery report received from carrier. Allow upto 72hrs or use validity in send-sms call to process. |
| bounced | Total number of soft and hard bounces recorded |
| responses | Replies received |
| opt-outs | Recipients opted out Either by reply or unsub link. |
| link_hits | Number of link hits recorded |
SUCCESS\n This will return paginated information regarding individual recipients on a campaign or message send.
\n| KEY | TYPE | DESCRIPTION | REQUIRED | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| message_id | integer | Numeric ID assigned to the message sent. This ID was returned in the send-sms response | YES | ||||||||
| list_id | integer | Recipient list This ID is the numerical reference to one of your recipient lists. It is found in the URL and displayed on a destination list page in your account. Provide list_id if contact is not associated with a campaign send. It will look up custom data on this list for the contact and return it in the response. | NO | ||||||||
| page | integer | Page number, for pagination | NO | ||||||||
| max | integer | Maximum results returned per page | NO | ||||||||
| delivery | boolean | Only show messages with specific delivery status.
| NO | ||||||||
| optouts | boolean | Whether to include opt outs
|
| PARAMETER | DESCRIPTION | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| message | Information about a message or campaign that you have sent
| ||||||||||||||||||||||||||
| recipients | A paginated report of all the recipients delivered to in your message/campaign
|
SUCCESS\n Retrieve information on messages sent during a period of time\nIt will also return all custom data fields associated to contacts in the list
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| start | datetime | A date to start the report from start and end date must be within 30 days \nIf start and end date not supplied will get everything from last 24 hrs only. | NO |
| end | datetime | A date to end the report at start and end date must be within 30 days \nIf start and end date not supplied will get everything from last 24 hrs only. | NO |
| list_id | integer | Recipient list Provide list_id to look up custom data on this list for the contact and return it in the response. | NO |
| number | integer | Virtual mobile number assigned to your account | NO |
| type | integer | Message type, available options: - all - api - campaign - quick_sms - email_sms - keyword - test_sms\n | NO |
| page | integer | Page number, for pagination | NO |
| max | integer | Maximum results returned per page | NO |
| response_style | string | response_style = 'array' returns custom field lists as an array | NO |
This will return paginated information regarding individual contacts on a list and their data.
\n| KEY | TYPE | DESCRIPTION | REQUIRED | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| list_id | integer | Numeric ID assigned to the list being queried List ID's can be retrieved using get-lists | YES | ||||||||
| page | integer | Page number, for pagination | NO | ||||||||
| max | integer | Maximum results returned per page | NO | ||||||||
| members | boolean | Only show contacts with specific status Returns all contacts if not specified.
| NO | ||||||||
| response_style | string | response_style = 'array' returns custom field lists as an array | NO |
| PARAMETER | DESCRIPTION | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| members_total | Count of number of contacts on list This will include deleted contacts. | ||||||||||||||||||
| id | Numeric ID of list | ||||||||||||||||||
| name | Name of list | ||||||||||||||||||
| created | Date list was first created | ||||||||||||||||||
| members_active | Count of active contacts on list | ||||||||||||||||||
| fields | Custom field name List of custom field names by field_n where n = is an integer between 1 and 10. | ||||||||||||||||||
| members | Information about contacts on the list
|
SUCCESS\n This will return metadata on all your lists
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| page | integer | Page number, for pagination | NO |
| max | integer | Maximum results returned per page | NO |
| response_style | string | response_style = 'array' returns custom field lists as an array | NO |
| PARAMETER | DESCRIPTION | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| lists_total | Count of number of lists in your account | ||||||||||||
| lists | Information about lists in your account
|
SUCCESS\n | KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| list_id | integer | Numeric ID of the list contact is on | YES |
| msisdn | integer | Mobile number of contact being queried | YES |
| response_style | string | response_style = 'array' returns custom field lists as an array | NO |
| PARAMETER | DESCRIPTION | ||||
|---|---|---|---|---|---|
| list_id | Numeric ID of the list contact is on | ||||
| msisdn | Mobile number of contact | ||||
| first_name | First name of contact | ||||
| last_name | Last name of contact | ||||
| created_at | Date and time that contact was first added to list Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||
| status | Status of contact
| ||||
| fields | Custom field value List of custom field values by field name. |
Get information about a message or campaign that you have sent
\n","event":[{"listen":"prerequest","script":{"id":"eca8741b-e382-4ab8-a6a0-41f5133e72ca","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"ebd0d2bd-a4d8-4776-9a34-027fa4b2b371","type":"text/javascript","exec":[""]}}],"_postman_id":"3d4c3657-0efc-4a2a-a0d2-574537f3d6bc"},{"name":"Contacts & Lists","item":[{"name":"Add List","id":"689eca8b-3657-488d-87c9-7dd69f70a3c3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://api.transmitsms.com/add-list.json","description":"| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| name | string | A unique name for the list | YES |
| field_n | string | Custom field name Firstname and lastname are created by default, There can be up to 10 extra custom fields. n is an integer between 1 and 10. | NO |
| response_style | string | response_style = 'array' returns custom field lists as an array | NO |
| PARAMETER | DESCRIPTION | ||||||
|---|---|---|---|---|---|---|---|
| id | A unique name for the list | ||||||
| name | Custom field name Firstname and lastname are created by default, There can be up to 10 extra custom fields. n is an integer between 1 and 10. | ||||||
| created | Date and time list was created Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||||
| members_active | Always returns 0 for new list | ||||||
| fields | Names of created custom fields | ||||||
| errors | Error messages related to this call, for general errors see the API Introduction
|
SUCCESS\n | KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| list_id | integer | ID of the list to add to | YES |
| field_n | string | Custom field name Firstname and lastname are created by default, There can be up to 10 extra custom fields. n is an integer between 1 and 10. | YES (at least 1) |
| response_style | string | response_style = 'array' returns custom field lists as an array | NO |
| PARAMETER | DESCRIPTION | ||||||
|---|---|---|---|---|---|---|---|
| custom_n | Custom field names created | ||||||
| id | ID of the list added to | ||||||
| error | Error messages related to this call, for general errors see the API Introduction
|
SUCCESS\n | PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| list_id | integer | Numeric ID of list to be removed. List ID's can be retrieved with get-lists request. | YES |
SUCCESS\n If a contact is added that already exists it will be ignored, not updated.
\n| KEY | TYPE | DESCRIPTION | REQUIRED | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| list_id | integer | ID of the list to be added to A list ID can also be created using the add-list call. | YES | ||||||||||||||||||||
| msisdn | string | Mobile number being added to list Invalid numbers will be ignored. Number must be defined in E.164 international format. You can use countrycode parameter to format numbers that are in local format. | YES | ||||||||||||||||||||
| countrycode | string | Format the to number in international format. 2 letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery. eg. In Australia 0422222222 will become 6142222222 when set to AU or Australia. If not set to numbers must be defined in E.164 international format.
| NO | ||||||||||||||||||||
| first_name | string | First name of contact being added | NO | ||||||||||||||||||||
| last_name | string | Last name of contact being added | NO | ||||||||||||||||||||
| field_n | string | Custom field name Firstname and lastname are created by default, There can be up to 10 extra custom fields. n is an integer between 1 and 10. | NO | ||||||||||||||||||||
| response_style | string | response_style = 'array' returns custom field lists as an array | NO |
| PARAMETER | DESCRIPTION | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| list_id | Numeric ID of the list that contact was added to | ||||||||||||||||||
| msisdn | Mobile number of contact that was added | ||||||||||||||||||
| firstname | First name of contact added | ||||||||||||||||||
| lastname | Last name of contact added | ||||||||||||||||||
| created_at | Date and time contact was added Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||||||||||||||||
| status | Status of contact This is always set to active with this request. | ||||||||||||||||||
| fields | Values assigned to custom fields | ||||||||||||||||||
| errors | Error messages related to this call, for general errors see the API Introduction
|
SUCCESS\n Used for adding new or updated custom data to a contact on a list.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
list_id | integer | ID of the list to be added to A list ID can also be created using the add-list call. | YES |
msisdn | string | Mobile number of contact being updated. Invalid numbers will be ignored. Number must be defined in E.164 international format. | YES |
first_name | string | First name of contact being added | NO |
last_name | string | Last name of contact being added | NO |
field_n | string | Custom field name Firstname and lastname are created by default, There can be up to 10 extra custom fields. n is an integer between 1 and 10. | NO |
| PARAMETER | DESCRIPTION | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
list_id | Numeric ID of the list that contact was added to | ||||||||||||||||||
msisdn | Mobile number of contact that was added | ||||||||||||||||||
firstname | First name of contact added | ||||||||||||||||||
lastname | Last name of contact added | ||||||||||||||||||
created_at | Date and time contact was added Returned in ISO8601 format YYYY-MM-DD HH:MM:SS in UTC Timezone. | ||||||||||||||||||
status | Status of contact This is always set to active with this request. | ||||||||||||||||||
fields | Values assigned to custom fields | ||||||||||||||||||
errors | Error messages related to this call, for general errors see the API Introduction
|
SUCCESS\n | PARAMETER | TYPE | DESCRIPTION | REQUIRED | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| list_id | integer | Numeric ID of list to remove contact from. If set to 0 (zero) the contact will be removed from all lists. | NO | ||||||||||||||||||||
| msisdn | integer | Mobile number of contact being removed. Number must be defined in E.164 international format. You can use countrycode parameter to format numbers that are in local format. | YES | ||||||||||||||||||||
| countrycode | string | Format the to number in international format. 2 letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery. eg. In Australia 0422222222 will become 6142222222 when set to AU or Australia. If not set to numbers must be defined in E.164 international format.
| NO |
| PARAMETER | DESCRIPTION | ||||||
|---|---|---|---|---|---|---|---|
| list_ids | One or more list ID's that contact was removed from | ||||||
| error | Error messages related to this call, for general errors see the API Introduction
|
SUCCESS\n Unsubscribe contact from one or all lists
If sending marketing by law you must enable an unsubscribe method. Anti-Spam Policy
| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
list_id | integer | Numeric ID of list to opt out contact from. If set to 0 (zero) the contact will be opted out from all lists. | NO |
msisdn | integer | Mobile number of contact being opted out. Number must be defined in E.164 international format. | YES |
| PARAMETER | DESCRIPTION | ||||||
|---|---|---|---|---|---|---|---|
list_ids | One or more list ID's that contact was opted out of. | ||||||
error | Error messages related to this call, for general errors see the API Introduction
|
SUCCESS\n The add-contacts-bulk request can be used to add a CSV file of contacts to an existing list. It can also be used to create a new list and upload a CSV file of contacts to it. If a contact is added that already exists in a list, any existing data will be updated.
\nThe return code 200 is only used to indicate that the API call has successfully hit our server. It in no way indicates if the contacts have been added\\updated successfully.\nTo find the status of an upload, including error messages, you must use the add-contacts-bulk-progress endpoint.
\nCSV File Format and Example:\n Firstname,Lastname,Mobile,\"Custom Field 1\"\n Jane,Doe,61412345678,10.44\n\nThe minimum required for successful import is Mobile.\n\nThe order above must be followed.\n| PARAMETER | TYPE | DESCRIPTION | REQUIRED | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| list_id | integer | ID of the list to be added to | If name is not set | ||||||||||||||||||||
| name | string | Name of the list to create and add contacts to If this is set a new list will be created with this name. The list ID will be returned in the API response. | If list_id not set | ||||||||||||||||||||
| countrycode | string | Format the to number in international format. 2 letter ISO 3166 format country code or country name. Automatically formats numbers to international format required for reliable SMS delivery. eg. In Australia 0422222222 will become 6142222222 when set to AU or Australia. If not set to numbers must be defined in E.164 international format.
| NO | ||||||||||||||||||||
| file_url | url | URL location of the CSV file containing the contact list.
| NO | field_n | string | Create or map a custom field
| NO |
SUCCESS\n For large lists in excess of 50,000 contacts, it can take some time to process. This request will let you see the progress of the import.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| list_id | integer | ID of the list to be checked | YES |
| PARAMETER | DESCRIPTION | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| list_id | ID of the list being checked | ||||||||
| status | Status of upload
| ||||||||
| importlength | Total number of records in file This count will include invalid numbers | ||||||||
| completed | Number of contacts processed This gives us an update of all numbers processed, should = importlength when complete. | ||||||||
| duplicates | Number of duplicate contacts excluded from import Any number that matches an existing contact on the list will not be imported. Only first record imported is kept. | ||||||||
| skipped | Number of rows in file skipped Can be caused by blank rows, invalid numbers or rows with a blank record in the mobile column. | ||||||||
| optout | Number of contacts that were already opted out. | ||||||||
| imported | Number of contacts successfully imported. |
SUCCESS\n Create a new list including optional custom fields.
\n","event":[{"listen":"prerequest","script":{"id":"232e4ac4-5e6c-45fc-bc52-aa29064d7259","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"4d79f5d2-ca5d-40e4-b960-40e3e7135a81","type":"text/javascript","exec":[""]}}],"_postman_id":"c45e4314-76cd-423a-ba91-63cfcbff736b"},{"name":"Numbers","item":[{"name":"Add Dedicated Virtual Number","id":"b1f72672-9248-4f28-ac57-0910110582cf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://api.transmitsms.com/lease-number.json","description":"Dedicated virtual numbers are used to receive MO (Mobile Originated) messages. They also make sure that all of your messages are sent from a number that is always the same. Dedicated Virtual Number availability is limited to certain countries. Check Global Sender ID Information for availability for your destination coutry.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
number | integer | Number to lease Omit this field to be given a random number. Use get-numbers to find out which numbers are currently available. | NO |
forward_url | url | Assign a callback URL to the number Will override the default Reply Callback URL if set in the SETTINGS section of your account. |
| PARAMETER | DESCRIPTION |
|---|---|
number | Number assigned to your account |
price | Monthly cost of number leased In account currency |
next_charge | Date of next monthly charge. In ISO8601 format YYYY-MM-DD Eg. 2020-04-27 |
auto_renew | Returns auto_renew status of number. Always returns true for new number |
Edit inbound options for a dedicated virtual number.
\nGet a list of numbers leased by you or available to be leased.
\nDedicated virtual numbers are used to receive MO (Mobile Originated) messages. They also make sure that all of your messages are sent from a number that is always the same. Dedicated Virtual Number availability is limited to certain countries. Check Global SMS delivery list for availability for your destination country.
\n| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| filter | string | Choose owned or available owned - retrieve your own response numbers (default) available - retrieve response numbers available for purchase | NO |
| page | integer | Page number, for pagination | |
| max | integer | Maximum results returned per page |
| PARAMETER | DESCRIPTION | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| page | Count: Number of pages, Number: Page number | ||||||||||
| numbers_total | Total amount of numbers leased | ||||||||||
| numbers | Data about each leased number
|
SUCCESS\n Get detailed information about a number you have leased.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| number | integer | Number to retrieve Omit this field to be given a random number. Use get-numbers to find out which numbers are currently available. | YES |
| PARAMETER | DESCRIPTION | ||||||
|---|---|---|---|---|---|---|---|
| number | Number assigned to your account | ||||||
| price | Monthly cost of number leased In account currency | ||||||
| next_charge | Date of next monthly charge. In ISO8601 format YYYY-MM-DD Eg. 2020-04-27 | ||||||
| auto_renew | Returns auto_renew status of number. Always returns true for new number | ||||||
| status | Status of number Returns active | ||||||
| error |
|
SUCCESS\n Edit inbound options for a dedicated virtual number.
\nThese options adjust behaviour for messages that are sent to this number.
\n| KEY | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| number | integer | Dedicated virtual number assigned to your account | YES |
| forward_email | email address | Forward incoming SMS to a set of email addresses Emails can be comma separated | NO |
| forward_sms | integer | Forward incoming SMS to a set of mobile numbers Numbers must be in international format. Can be comma separated. | NO |
| forward_url | url | Forward incoming messages to a callback URL | NO |
| list_id | integer | Add senders of incoming messages to this list | NO |
| welcome_message | string | Auto responder for all messages received | NO |
| members_message | string | Auto-response if the number is already on the list. Must be adding the number to a list | NO |
SUCCESS\n Lease a new dedicated number
\n","event":[{"listen":"prerequest","script":{"id":"e921304a-23be-4982-a8c5-4566de8d6145","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"f99780af-d7f7-47a8-b72d-1297d3c5ea97","type":"text/javascript","exec":[""]}}],"_postman_id":"fa6585fa-54af-4213-b86e-482abb829c4f"},{"name":"Email SMS","item":[{"name":"Add Email","id":"ed57a988-28ce-409e-905e-b1d5bfc3d45b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://api.transmitsms.com/add-email.json","description":"| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| email address | Email address to register. You may also register a wild-card email which allows any user on the same domain to use Email to SMS. Wild-card format: *@example.com | YES | |
| max_sms | integer | The maximum number of SMS messages to send from one email message sent from this email address. Possible values: 1 - up to 160 characters (default) 2 - up to 306 characters 3 - up to 459 characters 4 - up to 612 characters | NO |
| number | integer | Optional dedicated virtual number | NO |
SUCCESS\n Remove an email address from the Email to SMS authorised list.
\n| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| email address | Email address to remove. You may also use a wild-card email which removes all emails on that domain. Wild-card format: *@example.com | YES |
SUCCESS\n Authorise an email address for sending Email to SMS
\n","event":[{"listen":"prerequest","script":{"id":"8f78531f-a6fd-4ae5-a622-b96af39e200f","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"3565ff0a-1fa0-47c6-9a61-6541e1541a51","type":"text/javascript","exec":[""]}}],"_postman_id":"351d6617-c1ad-4965-9a06-11c3f2df5d44"},{"name":"Keywords","item":[{"name":"Add Keyword","id":"f60c580a-9252-4c68-bbc9-7efc4ad01738","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://api.transmitsms.com/add-keyword.json","description":"| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| keyword | string | The first word of a text message | YES |
| number | integer | The dedicated virtual number that the keyword belongs to | YES |
| reference | string | Your own reference (up to 100 characters) | NO |
| list_id | integer | ID of a list to add respondents to, list ID's can be found in the title of a list or in the list page URL | NO |
| welcome_message | string | SMS message to send to new members | NO |
| members_message | string | SMS message to existing members | NO |
| activate | boolean | Whether to make the keyword active immediately. Possible values: true - activate immediately (default) false - create the keyword but do not activate | NO |
| forward_url | url | Forward messages to a URL | NO |
| forward_email | email address | Forward messages to a set of email addresses | NO |
| forward_sms | integer | Forward messages to a set of msisdns | NO |
SUCCESS\n Edit an existing keyword.
\n| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| keyword | string | The first word of a text message | YES |
| number | integer | The dedicated virtual number that the keyword belongs to | YES |
| reference | string | Your own reference (up to 100 characters) | NO |
| status | string | Open, will set the Keyword to being active. Closed, will close the Keyword. | NO |
| list_id | integer | ID of a list to add respondents to, list ID's can be found in the title of a list or in the list page URL | NO |
| welcome_message | string | SMS message to send to new members | NO |
| members_message | string | SMS message to existing members | NO |
| activate | boolean | Whether to make the keyword active immediately. Possible values: true - activate immediately (default) false - create the keyword but do not activate | NO |
| forward_url | url | Forward messages to a URL | NO |
| forward_email | email address | Forward messages to a set of email addresses | NO |
| forward_sms | integer | Forward messages to a set of msisdns | NO |
SUCCESS\n Get a list of existing keywords.
\n| PARAMETER | TYPE | DESCRIPTION | REQUIRED |
|---|---|---|---|
| number | integer | Filter the list by virtual number | NO |
| page | integer | Page number, for pagination | NO |
| max | integer | Maximum results returned per page | NO |
SUCCESS\n Add a keyword to an existing virtual number
\n","event":[{"listen":"prerequest","script":{"id":"ea68eb90-2e08-4e32-a055-e25890c32355","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"4fcea8b2-8fb0-4216-b510-bd7eb5f0f7db","type":"text/javascript","exec":[""]}}],"_postman_id":"96325783-0fe3-49f5-b440-8aaff1c67abe"},{"name":"Account","item":[{"name":"Get Balance","id":"0b57abf4-b2a7-4391-a147-f546682913b1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.transmitsms.com/get-balance.json","description":"SUCCESS\n Get a summary of your account balance
\n","event":[{"listen":"prerequest","script":{"id":"8211c45f-665c-4e80-9968-5e40b746c5ae","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"bf2fc222-68be-4fc1-bb97-8586556bc540","type":"text/javascript","exec":[""]}}],"_postman_id":"05c0514b-89a6-41c2-9f6a-070e12622254"}],"event":[{"listen":"prerequest","script":{"id":"d51eb3b0-e097-405d-9a9f-1dfedf80365d","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"bc2388d3-6a94-4c05-91c8-9cfd27b9b8d9","type":"text/javascript","exec":[""]}}]}