ClickSend REST API v3

OpenAPI apis-guru email

This is the official API documentation for ClickSend.com

Below you will find a current list of the available methods for clicksend.

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

You can .

API URL

The API should always be accessed over SSL.

Base URL: https://rest.clicksend.com/v3/

Authentication

Basic HTTP authentication should be used in the header.

Either:

username: Your API username

password: Your API key

username: Your account username

password: Your account password

Authorization Header

The Authorization header is constructed as follows:

Username and password are combined into a string username:password
The resulting string is then encoded using Base64 encoding
The authorization method and a space i.e. "Basic " is then put before the encoded string.

For example, if the user uses Aladdin as the username and open sesame as the password then the header is formed as follows:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

PHP Authentication Header Example (using cURL)

curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Basic ' . base64_encode("$username:$password")]);

Verbs

The API uses restful verbs.

Verb	Description
`GET`	Select one or more items. Success returns `200` status code.
`POST`	Create a new item. Success returns `200` status code.
`PUT`	Update an item. Success returns `200` status code.
`DELETE`	Delete an item. Success returns `200` status code.

Status Codes

The API will respond with one of the following HTTP status codes.

Code	Response	Description
`200`	`SUCCESS`	Request completed successfully.
`400`	`BAD_REQUEST`	The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
`401`	`UNAUTHORIZED`	Authentication credentials were missing or incorrect.
`403`	`FORBIDDEN`	The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why.
`404`	`NOT_FOUND`	The URI requested is invalid or the resource requested does not exists.
`405`	`NOT_FOUND`	Method doesn't exist or is not allowed.
`429`	`TOO_MANY_REQUESTS`	Rate Limit Exceeded. Returned when a request cannot be served due to the application’s rate limit having been exhausted for the resource. See Rate Limiting.
`500`	`INTERNAL_SERVER_ERROR`	Something is broken

Application Status Codes

The following status codes can be returned in addition to the HTTP status code. For example, when using the Send SMS endpoint:

Response	Description
`SUCCESS`	Message added to queue OK. Use delivery reports to get an update on the delivery status.
`MISSING_CREDENTIALS`	Not enough information has been supplied for authentication. Please ensure that your Username and Unique Key are supplied in your request.
`ACCOUNT_NOT_ACTIVATED`	Your account has not been activated.
`INVALID_RECIPIENT`	The destination mobile number is invalid.
`THROTTLED`	Identical message body recently sent to the same recipient. Please try again in a few seconds.
`INVALID_SENDER_ID`	Invalid Sender ID. Please ensure Sender ID is no longer than 11 characters (if alphanumeric), and contains no spaces.
`INSUFFICIENT_CREDIT`	You have reached the end of your message credits. You will need to purchase more message credits.
`INVALID_CREDENTIALS`	Your Username or Unique Key is incorrect.
`ALREADY_EXISTS`	The resource you're trying to add already exists.
`EMPTY_MESSAGE`	Message is empty.
`TOO_MANY_RECIPIENTS`	Too many recipients.
`MISSING_REQUIRED_FIELDS`	Some required fields are missing.
`INVALID_SCHEDULE`	The schedule specified is invalid. Use a unix timestamp e.g. 1429170372.
`NOT_ENOUGH_PERMISSION_TO_LIST_ID`	Don't have enough privilege to access or send to a list_id.
`INTERNAL_ERROR`	Internal error.
`INVALID_LANG`	An invalid language option has been provided.
`INVALID_VOICE`	An invalid voice (gender) option has been provided.
`SUBJECT_REQUIRED`	Usually happens when MMS Subject is empty.
`INVALID_MEDIA_FILE`	Usually MMS media file is invalid file.
`SOMETHING_IS_WRONG`	Generic Error happened.

Required Headers

You'll need to send some headers when making API calls.

Header	Value
`Content-type`	`application/json`

Pagination

Some methods are paginated. By default, 1 page of 15 items will be returned. You can set the pagination parameters by adding ?page={page}&limit={limit} to the URL.

Request

Parameter	Type	Default	Value
`page`	integer	`1`	The page number to return in the response.
`limit`	integer	`15`	The number of results per page. Min 15, Max 100.

Response

| Attribute | Type | Value | |---|---|---|---| | total | integer | Total number of results available. | | per_page | integer | Number of results returned per page. | | current_page | integer | Current page number. | | last_page | integer | Last page number. | | next_page_url | string | A URL of the next page. null if not available.| | prev_page_url | string | A URL of the previous page. null if not available.| | from | integer | Number of the first result in current page. | | to | integer | Number of the last result in current page. |

Searching and Sorting

Most GET endpoints allow searching and sorting. Searches are not case-sensitive.

Search

To perform a search, add q as a query parameter. For example:

/subaccounts?q=field:value,field2:value

Order

To perform a sort, add order_by as a query parameter. For example:

/subaccounts?order_by=field:desc/asc

AND / OR

By default, it will search using the AND operator. This can be set using operator as a query parameter. For example:

/subaccounts?q=field:value&operator=OR

Options:

AN - returns results matching all query fields specified
OR - returns results matching any query fields specified

Example

/subaccounts?q=first_name:john,last_name:smith&order_by=subaccount_id:asc&operator=AND

CORS

When creating your API app, specify the JavaScript (CORS) origins you'll be using. We use these origins to return the headers needed for CORS.

Date and Time

All date/timestamps will be returned in Unix time (also known as POSIX time or erroneously as Epoch time) with no leap seconds.

For example: 1435255816

More information: .

There is ony one Unix time and it is created by using the UTC/GMT time zone. This means you might have convert time zones to calculate timestamps. Most programming language have libraries to help you converting time zones.

The current Unix time can be found here:

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/MMS 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
+8615555555555

Test Voice 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
+8615555555555

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

+61261111111
+61262222222
+61263333333

Test Email Addresses

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

test1@test.com
test2@test.com
test3@test.com

Test Post Letter Addresses

The following Postal Codes (address_postal_code) can be used when testing. No messages will be sent when using these post codes, and your account won't be charged. A success response will be returned.

11111
22222
33333

Homepage: https://api.apis.guru/v2/specs/clicksend.com/1.0.0.json
Provider: clicksend.com
OpenAPI version: 3.0.0
Spec (JSON): https://api.apis.guru/v2/specs/clicksend.com/1.0.0/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/clicksend.com/1.0.0/openapi.yaml

Tools (207)

Extracted live via the executor SDK.

account.accountUsage
account.createANewAccount

Note: Authentication isn't required to create a new account.
account.getAccount
account.sendAccountActivationToken
account.updateAccount
account.verifyNewAccount
accountRecharge.getASpecificTransaction
accountRecharge.getCreditCardInfo
accountRecharge.getTransactions
accountRecharge.listOfPackages
accountRecharge.purchaseAPackage
accountRecharge.updateCreditCardInfo
automationRules.createANewRulePost005ak1x7
automationRules.createANewRulePost00lknu58
automationRules.deleteARuleDelete003v85n9
automationRules.deleteARuleDelete0056zvpl
automationRules.deleteAutomationsEmailReceiptRuleId
automationRules.deleteAutomationsFaxInboundInboundRuleId
automationRules.deleteAutomationsSmsReceiptsReceiptRuleId
automationRules.deleteAutomationsVoiceReceiptsReceiptRuleId
automationRules.getASpecificRuleGet005iyn9p
automationRules.getASpecificRuleGet00corki7
automationRules.getAutomationsEmailReceipt
automationRules.getAutomationsEmailReceiptRuleId
automationRules.getAutomationsFaxInbound
automationRules.getAutomationsFaxInboundInboundRuleId
automationRules.getAutomationsSmsReceipts
automationRules.getAutomationsSmsReceiptsReceiptRuleId
automationRules.getAutomationsVoiceReceipts
automationRules.getAutomationsVoiceReceiptsReceiptRuleId
automationRules.listRulesGet00ab49xg
automationRules.listRulesGet00f7zu16
automationRules.postAutomationsEmailReceipt
automationRules.postAutomationsFaxInbound
automationRules.postAutomationsSmsReceipts
automationRules.postAutomationsVoiceReceipts
automationRules.putAutomationsEmailReceiptRuleId
automationRules.putAutomationsFaxInboundInboundRuleId
automationRules.putAutomationsSmsReceiptsReceiptRuleId
automationRules.putAutomationsVoiceReceiptsReceiptRuleId
automationRules.updateARulePut00ph1niv
automationRules.updateARulePut00vusnuh
contactLists.createANewContactList
contactLists.deleteASpecificContactList
contactLists.exportContactsList
contactLists.getAllContactLists
contactLists.getASpecificContactList
contactLists.getListOfAcceptableImportFields
contactLists.importContactsToList
contactLists.removeDuplicateContacts
contactLists.showCsvImportFilePreview

Show first row of the csv import file.
contactLists.updateASpecificContactList
contacts.createANewContact

Note that the fields phone_number, fax_number and email are all optional; however at least one of them must be specified, otherwise the API call will fail.
contacts.deleteASpecificContact
contacts.getAllContactsInAList
contacts.getASpecificContact
contacts.removeOptedOutContacts
contacts.transferAContact

Transfers a specific contact to another list.
contacts.updateASpecificContact
contactSuggestions.listContactSuggestions
countries.getAllCountries
deliveryIssues.createDeliveryIssue
deliveryIssues.getDeliveryIssues
emailMarketing.calculatePrice
emailMarketing.cancelEmailCampaign
emailMarketing.createAllowedEmailAddress
emailMarketing.createEmailCampaign
emailMarketing.createNewEmailTemplateFromMasterTemplate
emailMarketing.deleteAllowedEmailAddress
emailMarketing.deleteEmailTemplate
emailMarketing.getAllAllowedEmailAddresses
emailMarketing.getAllEmailCampaigns
emailMarketing.getAllEmailTemplates
emailMarketing.getAllMasterEmailTemplates
emailMarketing.getAllMasterTemplateCategories
emailMarketing.getAllTemplatesForCategory
emailMarketing.getSpecificAllowedEmailAddress
emailMarketing.getSpecificEmailCampaign
emailMarketing.getSpecificEmailCampaignHistory
emailMarketing.getSpecificEmailTemplate
emailMarketing.getSpecificEmailTemplateCategory
emailMarketing.getSpecificMasterTemplate
emailMarketing.sendVerificationToken
emailMarketing.updateAnEmailTemplate
emailMarketing.updateEmailCampaign
emailMarketing.uploadImageToSpecificTemplate
emailMarketing.verifyAllowedEmailAddress
emailToSmsAllowedAddress.createEmailToSmsAllowedAddress

Create an allowed email address.
emailToSmsAllowedAddress.deleteEmailToSmsAllowedAddress

Delete a specific allowed email address.
emailToSmsAllowedAddress.getSpecificEmailToSmsAllowedAddress

Get a specific allowed email address.
emailToSmsAllowedAddress.listOfEmailToSmsAllowedAddress

Get list of allowed email addresses.
emailToSmsAllowedAddress.updateEmailToSmsAllowedAddress

Update a specific allowed email address.
emailToSmsStrippedStrings.createStrippedString
emailToSmsStrippedStrings.deleteStrippedString
emailToSmsStrippedStrings.findSpecificStrippedString
emailToSmsStrippedStrings.listStrippedStrings
emailToSmsStrippedStrings.updateStrippedString
fax.addATestDeliveryReceipt
fax.exportFaxHistory
fax.getASpecificFaxDeliveryReceipt
fax.getFaxHistory

Get a list of Fax History.
fax.listOfFaxDeliveryReceipts
fax.markFaxDeliveryReceiptsAsRead
fax.postFaxPrice
fax.sendFax

Letter File Options
Use existing URL
With this option, you can use an existing URL to a PDF document. For example, you might generate the pdf on your server.
Upload File to Our Server
With this option, you can use the /uploads endpoint to upload the document. The /uploads endpoint returns a URL that can be used in the /fax/send endpoint.
forgotAccount.forgotPassword
forgotAccount.forgotUsername
forgotAccount.verifyForgotPassword
mms.cancelAllMms
mms.cancelMms
mms.exportMmsHistory
mms.getAllDeliveryReceipts
mms.getDeliveryReceipt
mms.getMmsHistory
mms.getPrice
mms.markReceiptsAsRead
mms.sendMms
numbers.buyDedicatedNumber
numbers.getAllDedicatedNumbers
numbers.searchDedicatedNumbersByCountry
postAddressDetection.detectAddress
The detect-address endpoint accepts either a letter in PDF format or an address string and attempts to convert it to a standard address format. Note that the PDF should be in standard address format, having the recipient's name and address listed at the top.
The endpoint accepts two types of data:
1. A PDF file in base64 encoding. In this case, submit the base64-encoded PDF file contents in the content field of the request body.
2. An address string. In this case, submit the address in a string using the address field of the request body.
postcards.calculatePricing
For file_urls field. You can attach at least 1 and max of 2 PDF file urls.
- Supply a single pdf with 2 pages (front and back)
- Supply 2 urls to seperate PDFs
postcards.exportPostcardHistory
postcards.getPostcardHistory
postcards.sendPostcard
Supported File Types We support PDF, docx and doc. Contact us to add support for any other file type. If you're using docx or doc files, you'll need to convert the file first using our uploads endpoint with the querystring parameter ?convert=post. e.g. POST /uploads?convert=post. This will return a URL to the converted pdf file that can be used in the /post/postcards/send endpoint.
Postcard File Options
Use existing URL
With this option, you can use an existing URL to a PDF document. For example, you might generate the pdf on your server.
For file_urls field. You can attach at least 1 and max of 2 PDF file urls.
- Supply a single pdf with 2 pages (front and back)
- Supply 2 urls to seperate PDFs
Upload File to Our Server
With this option, you can use the /uploads endpoint to upload the document. The /uploads endpoint returns a URL that can be used in the /post/postcards/send endpoint.
postDirectMail.calculateDirectMailCampaignPrice

Calculate direct mail campaign price.
postDirectMail.createNewCampaign

Create new direct mail campaign.
postDirectMail.listDirectMailCampaigns

Get list of direct mail campaigns.
postDirectMail.searchLocations
postLetter.createAPostReturnAddress
postLetter.deletePostReturnAddress
postLetter.exportPostLetterHistory
postLetter.getListOfPostReturnAddresses
postLetter.getPostLetterHistory
postLetter.getPostReturnAddress
postLetter.postPostLettersPrice
postLetter.sendPostLetter

Supported File Types We support pdf, docx and doc files. Contact us to add support for any other file type. If you're using docx or doc files, you'll need to convert the file first using our uploads endpoint with the querystring parameter convert=post e.g. POST /uploads?convert=post. This will return a URL to the converted pdf file that can be used in the /post/letters/send endpoint.
Letter File Options
Use existing URL
With this option, you can use an existing URL to a pdf document. For example, you might generate the pdf on your server.
Upload File to Our Server
With this option, you can use the /uploads endpoint to upload the document. The /uploads endpoint returns a URL that can be used in the /post/letters/send endpoint.
postLetter.updatePostReturnAddress
pricing.getCountryPricing
referralAccounts.getListOfReferralAccounts
reseller.getResellerSetting

Get reseller setting.
reseller.resellerBySubdomain

Get reseller setting by subdomin.
reseller.updateResellerSetting

Update a specific reseller setting.
resellerAccounts.createResellerAccount
resellerAccounts.createResellerAccountPublic
resellerAccounts.getResellerAccount

Get a specific reseller account.
resellerAccounts.listOfResellerAccounts

Get list of Reseller Accounts
resellerAccounts.transferCredit
resellerAccounts.updateResellerAccount
sdk.sdkDownload
search.searchContactsLists
sms.addATestInboundSms
sms.cancelAllScheduledMessages
sms.cancelAScheduledMessage
sms.exportSmsHistory

sms.getAllHistory

SMS Delivery Status

Status (status field)

| Status | Description | |---|---|---| | Completed | Added to delivery queue. Waiting to be sent to the network.| | Sent | Message sent to the network.| | Cancelled | Message cancelled.| | Scheduled | Message scheduled.| | WaitApproval | Waiting approval by our team. This is temporary and will change to 'Sent' once approved. This only happens for a few messages that are flagged for approval by our automated spam-detection system.|

Status Codes (status_code field)

Code	Text	Description
`200`	Sent by network	Temporary success
`201`	Received on handset	Permanent success
`300`	Delivery failure	Permanent failure
`301`	Delivery failure	Permanent failure
`302`	Delivery failure	Temporary failure - supplier routing issue

sms.getAllInboundSmsPull
sms.getASpecificDeliveryReceipt
sms.getSmsReceipts
sms.getSpecificInboundPull
sms.markAllInboundSmsAsRead
sms.markASpecificInboundSmsAsRead
sms.markDeliveryReceiptsAsRead
sms.postSmsPrice
sms.postSmsReceipts
sms.sendAnSms

You can post up to 1000 messages with each API call.
smsCampaigns.calculatePriceForSmsCampaign
smsCampaigns.cancelAnSmsCampaign
smsCampaigns.getListOfSmsCampaigns
smsCampaigns.getSmsCampaign
smsCampaigns.linkStatistics

Get the breakdown of statistics for your campaign. Note that the returned values vary depending on your specific customers' interaction, so it's not safe to assume a value will always be specified.
smsCampaigns.linkTracking

This endpoint gives you a paginated overview of all the links in a particular campaign, and who has and hasn't visited them.
smsCampaigns.linkTrackingExport

Compile all link tracking for the specified campaign into a CSV for download.
smsCampaigns.updateAnSmsCampaign
smsCampaigns.useShortUrl

This is functionally identical to the POST /sms-campaigns/send endpoint, other than adding the smsg.us/xxxxx string to the message body additional url_to_shorten parameter.
smsTemplates.createATemplate

Create new template.
smsTemplates.deleteATemplate
smsTemplates.listOfTemplates

Get list of templates.
smsTemplates.updateATemplate
statistics.getSmsStatistics
statistics.getVoiceStatistics
subaccounts.createANewSubaccount
subaccounts.deleteASpecificSubaccount
subaccounts.getAllSubaccounts
subaccounts.getASpecificSubaccount
subaccounts.regenerateApiKey
subaccounts.updateASpecificSubaccount
timezones.getTimezones

Get supported list of timezones.
transactionalEmail.emailHistory
transactionalEmail.emailPrice
transactionalEmail.emailSend
transactionalEmail.exportHistory
transactionalEmail.postEmailReceipts
uploads.uploadAFile
voice.cancelAllVoiceCalls
voice.cancelASpecificVoiceCall
voice.exportVoiceHistory
voice.getSpecificVoiceReceipt
voice.getVoiceHistory
voice.getVoiceReceipts
voice.markedVoiceReceiptsAsRead
voice.postVoicePrice
voice.postVoiceReceipts
voice.sendAVoiceCall

You can post up to 1000 messages with each API call.
We support some SSML tags allowing custom breaks or pauses to be entered, and the readout rate to be altered. .
voice.voiceLanguages
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools