Introduction

ClickSend provides a HTTP API to enable developers to integrate SMS functionality into their applications. All services are accessible using either HTTP or HTTPS protocols.

NOTE: You will need to create a free account to use the API. You can register here..

API URL

The API should always be accessed over SSL.

Base URLs:

https://api-mapper.clicksend.com/http/v2/

Postman

If you would like to use Postman click this button to download our HTTP V2 API collection for instant use.

Simply import our collection and create an environment with username and password variables to get started.

Authentication

Your credentials should be used in the URL or the post body.

Either:

username - Your API username key - Your API key

username - Your subaccount username key - Your subaccount password

Response Codes

The API will always respond with a 200 OK HTTP status code.

Response Code	Error Text	Description
`0000`	Success	Message added to queue OK.
`2006`	Missing credentials	Not enough information has been supplied for authentication. Please ensure that your Username and Unique Key are supplied in your request.
`2007`	Account not activated	Your account has not been activated.
`2015`	Invalid recipient	The destination mobile number is invalid.
`2016`	Throttled	Identical message already sent to this recipient. Please try again in a few seconds.
`2017`	Invalid sender id	Invalid Sender ID. Please ensure Sender ID is no longer than 11 characters (if alphanumeric), and contains no spaces.
`2018`	Low credit	You have reached the end of your message credits. You will need to purchase more message credits.
`2022`	Invalid credentials	Your Username or Unique Key is incorrect.
`2051`	Empty message	Message is empty.
`2052`	Too many recipients	Too many recipients.
`2100-2199`	Internal error	Internal error.

Security

To ensure privacy, we recommend you use HTTPS for all API requests.

Incoming SMS/Reply Options

There are 5 options for handling message replies:

Send the reply as an email to a nominated email address.
Send the reply as an email to the original user who sent the message.
Send the reply as an SMS to a nominated mobile number.

Push - POST the reply to your website or application.

If you prefer, we can push message replies to your server as they arrive with us.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on SMS & MMS then Inbound Rules.
Click the 'Add New Rule' button.
Select the 'URL' action.
Enter the URL and click 'Save'.

The following parameters will be POSTED to the URL specified.

Parameter	Type	Description
`from`	string	Recipient Mobile Number that sent the reply message.
`message`	string	Reply SMS message body.
`originalmessage`	string	Original SMS message body.
`originalmessageid`	string	Original SMS message ID. Returned when originally sending the message.
`originalsenderid`	string	Original mobile number (sender ID) that the SMS was sent from.
`customstring`	string	A custom string used when sending the original message.
`username`	string	The API username used to send the original message.

Pull - Use our API to poll for replies.

Receive SMS by polling your Inbox. You can poll our server and retrieve new Messages at a time that suits you.
1. Log into your account.
2. Click on your profile on the top right.
3. Then click on the Messaging Settings option.
4. Click on SMS & MMS then Inbound Rules.
5. Click the 'Add New Rule' button.
6. Select the 'Poll' action.
7. Then click 'Save'.

Delivery Reports

PUSH

If you prefer, we can push message replies to your server as they arrive with us.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on SMS & MMS then Inbound Rules.
Click the 'Add New Rule' button.
Select the 'URL' action.
Enter the URL and click 'Save'.

The following parameters will be POSTED to the URL specified.

Parameter	Type	Description
`messageid`	string	SMS message ID. Returned when originally sending the message.
`status`	string	Delivery status. Either 'Delivered' or 'Undelivered'.
`status_code`	integer	Delivery status code. The temporary status codes can update at any time.
`customstring`	string	A custom string used when sending the original message.
`username`	string	The API username used to send the original message.

PULL

Receive delivery reports by polling. You can poll our server and retrieve delivery reports at a time that suits you.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on SMS & MMS then Inbound Rules.
Click the 'Add New Rule' button.
Select the 'Poll' action.
Then click 'Save'.

Note: a delivery report won't be generated when using a test number.

Testing

Test Credentials

These API credentials can be used to test specific scenarios.

Note: you will need to create a free account to test other scenarios. Refer to introduction.

API Username	API Key	Description
`nocredit`	`D83DED51-9E35-4D42-9BB9-0E34B7CA85AE`	This account has no credit.
`notactive`	`D83DED51-9E35-4D42-9BB9-0E34B7CA85AE`	This account is not active.
`banned`	`D83DED51-9E35-4D42-9BB9-0E34B7CA85AE`	This account is banned.

Test SMS Numbers

The following numbers can be used when testing. No messages will be sent, and your account won't be charged. A success response will be returned.

+61411111111
+61422222222
+61433333333
+61444444444
+14055555555
+14055555666
+447777777777
+447778888888
+8615555555555

A message added to queue 'Success' response will be returned. No SMS will actually be sent. This won't use any of your credit. A delivery report won't be generated when using a test number.

Account Balance

Code samples

    curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
       --request GET \
       --header "Content-Type: application/x-www-form-urlencoded" \
    'https://api-mapper.clicksend.com/http/v2/balance.php?username=myusername&key=094F2_FA56B10A_0F8F6B_A35FD650D829'

Request

    username=myusername&key=094F2_FA56B10A_0F8F6B_A35FD650D829

Response

    <?xml version='1.0' encoding='UTF-8' ?>
    <xml>
        <result>0000</result>
        <errortext>Success</errortext>
        <balance>125.00</balance>
        <type>Prepay</type>
        <currency_symbol>$</currency_symbol>
    </xml>

https://api-mapper.clicksend.com/http/v2/balance.php

Parameters

Parameter	In	Type	Required	Description
`username`	query	string	true	Your API username
`key`	query	string	true	You can find this in your account area under 'API Credentials' at the top of the screen.

SMS

Send an SMS

Code samples

    curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
       --request POST \
       --header "Content-Type: application/x-www-form-urlencoded" \
       --data-binary "username=myusername&key=1234-I3U2RN34IU-43UNG&to=61411111111,64122222222,61433333333&senderid=example&message=testing" \
    'https://api-mapper.clicksend.com/http/v2/send.php'

Request

        username=myusername&key=1234-I3U2RN34IU-43UNG&to=61411111111,61422222222,61433333333&senderid=example&message=testing

Response

  <?xml version="1.0" encoding="UTF-8"?>
  <xml>
      <messages recipientcount="1">
          <message>
              <to>+61411111111</to>
              <messageid>32794C10-F9CA-4E17-ABEC-F2F764EEC922</messageid>
              <result>0000</result>
              <errortext>Success</errortext>
              <price>0.0282</price>
              <currency_symbol>$</currency_symbol>
              <currency_type>USD</currency_type>
          </message>
      </messages>
  </xml>

There are two options for sending SMS depending on ease of use and the volume you wish to send.

HTTP POST

https://api-mapper.clicksend.com/http/v2/send.php

Ideal for up to 1000 simultaneous recipients in each API call.

Post the message you want to send and all the numbers you want the message to be sent to. Payload will be send in posted form variables rather than in the url.

For example:

https://api-mapper.clicksend.com/http/v2/send.php

POST Variables: method=http&username=xxxx&key=xxxx&to=xxxx,yyyy,zzzz&message=xxxx

HTTP GET

https://api-mapper.clicksend.com/http/v2/send.php

Ideal for less than 100 simultaneous recipients in each API call. The GET method uses a query string to send data using the URL. Maximum URL length is 2048 characters.

This is the simpler method to use, where the user can send the message just by entering the required information into the url.

For example:

https://api-mapper.clicksend.com/http/v2/send.php?method=http&username=xxxx&key=xxxx&to=xxxx,yyyy,zzzz&message=xxxx

If you need to send to more than 1000 simultaneous recipients at a time, try our REST V3 API which can send up to 20000 messages with a single api call.

Parameters

Parameter	In	Type	Required	Description
`username`	query	string	true	Your API username
`key`	query	string	true	You can find this in your account area under 'API Credentials' at the top of the screen.
`to`	query	string	true	Recipient Mobile Number in international format (with leading + and country code). Separate multiple recipients with a comma (,) where applicable. Maximum 1000 recipients.
`message`	query	string	true	The message to be sent. Maximum 960 characters.
`senderid`	query	string	false	custom sender ID (from name/number)
`schedule`	query	string	false	Allows you to schedule message delivery. Must be in unix format.
`country`	query	string	false	Automatically transforms your supplied local number to add the country code.

View all Inbound SMS

Code samples

    curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
       --request POST \
       --header "Content-Type: application/x-www-form-urlencoded" \
       --data-binary "username=myusername&key=094F2_FA56B10A_0F8F6B_A35FD650D829" \
    'https://api-mapper.clicksend.com/http/v2/reply.php'

Request

  username=myusername&key=094F2_FA56B10A_0F8F6B_A35FD650D829

Response

  <?xml version='1.0' encoding='UTF-8' ?>
  <xml>
      <replies replycount='2'>
          <reply>
              <from>+61411111111</from>
              <message>This is a reply</message>
              <originalmessage>Hello. Please reply</originalmessage>
              <originalmessageid>D9F15F83-34EC-6A31-A57E-7E8FB0966D78</originalmessageid>
              <originalsenderid>+61400000000</originalsenderid>
              <customstring></customstring>
              <username>testuser101</username>
          </reply>
          <reply>
              <from>+61422222222</from>
              <message>This is another reply</message>
              <originalmessage>Hello. Please reply</originalmessage>
              <originalmessageid>F15F83H8-15AC-3R31-777E-7E8FB09SSDP2</originalmessageid>
              <originalsenderid>+61400000000</originalsenderid>
              <customstring></customstring>
              <username>testuser101</username>
          </reply>
      </replies>
      <result>0000</result>
      <errortext>Success</errortext>
  </xml>

https://api-mapper.clicksend.com/http/v2/reply.php

Pull Inbound SMS

Receive SMS by polling your Inbox. You can poll our server and retrieve new Messages at a time that suits you.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on SMS & MMS then Inbound Rules.
Click the 'Add New Rule' button.
Select the 'Poll' action.
Then click 'Save'.

Push Inbound SMS

If you prefer, we can push message replies to your server as they arrive with us.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on SMS & MMS then Inbound Rules.
Click the 'Add New Rule' button.
Select the 'URL' action.
Enter the URL and click 'Save'.

Parameters

Parameter	In	Type	Required	Description
`username`	query	string	true	Your API username
`key`	query	string	true	You can find this in your account area under 'API Credentials' at the top of the screen.

View all Delivery Receipts

Code samples

    curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
       --request GET \
       --header "Content-Type: application/x-www-form-urlencoded" \
    'https://api-mapper.clicksend.com/http/v2/delivery.php?username=myusername&key=094F2_FA56B10A_0F8F6B_A35FD650D829'

Request

  username=myusername&key=094F2_FA56B10A_0F8F6B_A35FD650D829

Response

  <?xml version='1.0' encoding='UTF-8' ?>
  <xml>
      <dlrs dlrcount='2'>
          <dlr>
              <messageid>D9F15F83-34EC-6A31-A57E-7E8FB0966D78</messageid>
              <status>Delivered</status>
              <status_code>201</status_code>
              <customstring></customstring>
              <username>testuser101</username>
          </dlr>
          <dlr>
              <messageid>F15F83H8-15AC-3R31-777E-7E8FB09SSDP2</messageid>
              <status>Undelivered</status>
              <status_code>301</status_code>
              <customstring></customstring>
              <username>testuser101</username>
          </dlr>
      </dlrs>
      <result>0000</result>
      <errortext>Success</errortext>
  </xml>

https://api-mapper.clicksend.com/http/v2/delivery.php

Pull Delivery Receipts

Receive delivery reports by polling. You can poll our server and retrieve delivery reports at a time that suits you.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on SMS & MMS then Inbound Rules.
Click the 'Add New Rule' button.
Select the 'Poll' action.
Then click 'Save'.

Push Delivery Receipts

If you prefer, we can push message replies to your server as they arrive with us.

Log into your account.
Click on your profile on the top right.
Then click on the Messaging Settings option.
Click on SMS & MMS then Inbound Rules.
Click the 'Add New Rule' button.
Select the 'URL' action.
Enter the URL and click 'Save'.

Parameters

Parameter	In	Type	Required	Description
`username`	query	string	true	Your API username
`key`	query	string	true	You can find this in your account area under 'API Credentials' at the top of the screen.

View SMS History

Code samples

    curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
       --request GET \
       --header "Content-Type: application/x-www-form-urlencoded" \
    'https://api-mapper.clicksend.com/http/v2/history.php?username=myusername&key=094F2_FA56B10A_0F8F6B_A35FD650D829'

Request

  username=myusername&key=094F2_FA56B10A_0F8F6B_A35FD650D829

Response

  <?xml version='1.0' encoding='UTF-8' ?>
  <xml>
      <history historycount='2'>
          <item>
              <messageid>D9F15F83-34EC-6A31-A57E-7E8FB0966D78</messageid>
              <direction>out</direction>
              <date>1414291144</date>
              <to>+61411111111</to>
              <message>This is a test message</message>
              <status>Sent</status>
              <senderid>MyCompany</senderid>
              <schedule>1414291144</schedule>
              <customstring>our-ref-1234</customstring>
              <from_email>test@email.com</from_email>
          </item>
          <item>
              <messageid>F15F83H8-15AC-3R31-777E-7E8FB09SSDP2</messageid>
              <direction>in</direction>
              <date>1414291155</date>
              <to>+61422222222</to>
              <message>This is a test message reply</message>
              <status>Received</status>
              <senderid>+61411111111</senderid>
              <schedule></schedule>
              <customstring>our-ref-1234</customstring>
              <from_email>test@email.com</from_email>
          </item>
          <result>0000</result>
          <errortext>Success</errortext>
      </history>
  </xml>

https://api-mapper.clicksend.com/http/v2/history.php

Parameters

Parameter	In	Type	Required	Description
`username`	query	string	true	Your API username
`key`	query	string	true	You can find this in your account area under 'API Credentials' at the top of the screen.
`from_email`	query	string	false	The email address used to send the message if email-to-SMS was used. Only history results for this email address will be returned.