Post
/
Letters
/
Calculate Letter Price

Letters

Everything about Letters

Languages
Servers
https://rest.clicksend.com/

Send Letter

Request

Send letter

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 https://rest.clicksend.com/v3/uploads?convert=post. This will return a URL to the converted pdf file that can be used in the /post/letters/send endpoint.

Letter Specification Guide

Follow our Letter specification guide to ensure correct sending and letter template information.

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.

When using an existing url make sure that it is publicly accessible as it will not work if it is private.

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.

Properties

NameTypeRequiredRestrictionsDescription
file_urlstringtruenoneURL of file to send
address_namestringtruenoneName of address
address_line_1stringtruenoneFirst line of address
address_line_2stringtruenoneSecond line of address
address_citystringtruenoneCity
address_statestringtruenoneState
address_postal_codestringtruenonePostal code
address_countrystringtruenoneCountry
return_address_idinteger(int32)truenoneID of return address to use
scheduleinteger(int32)falsenoneWhen to send letter (0/null=now)
template_usedinteger(int1)falsenoneWhether using our letter template. Flag value must be 1 for yes or 0 for no.
duplexinteger(int1)falsenoneWhether letter is duplex. Flag value must be 1 for yes or 0 for no.
colourinteger(int1)falsenoneWhether letter is in colour. Flag value must be 1 for yes or 0 for no.
priority_postinteger(int1)falsenoneWhether letter is priority, Flag value must be 1 for yes or 0 for no.
sourcestringfalsenoneSource being sent from

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
Bodyapplication/json
file_urlstring
Example: "{{fileUrl}}"
template_usedinteger
Example: 1
colourinteger
duplexinteger
Example: 1
recipientsArray of objects
Example: [{"address_name":"test","address_city":"test","address_state":"test","address_postal_code":"6000","address_country":"AU","address_line_1":"1 test street","return_address_id":"{{addressId}}"}]
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \

     --header "Content-Type: application/json" \
     --data-binary "{
  \"file_url\": \"http://yourdomain.com/file.pdf\",
  \"template_used\": 1,
  \"colour\": 1,
  \"duplex\": 0,
  \"priority_post\": 0,
  \"recipients\": [
    {
      \"address_name\": \"My Home Address\",
      \"address_line_1\": \"Address 1\",
      \"address_line_2\": \"Address 2\",
      \"address_city\": \"CITY\",
      \"address_state\": \"State\",
      \"address_postal_code\": 123456,
      \"address_country\": \"AU\",
      \"return_address_id\": 1,
      \"custom_string\": \"Custom kn0ChLhwn6\",
      \"schedule\": 1449573604
    }
  ]
}" \
'https://rest.clicksend.com/v3/post/letters/send'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Letters queued for delivery."
dataobject
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Letters queued for delivery.",
  "data": {
    "recipients": [ … ],
    "_currency": { … }
  }
}

Calculate Letter Price

Request

Calculate letter price

Properties

NameTypeRequiredRestrictionsDescription
file_urlstringtruenoneURL of file to send
address_namestringtruenoneName of address
address_line_1stringtruenoneFirst line of address
address_line_2stringtruenoneSecond line of address
address_citystringtruenoneCity
address_statestringtruenoneState
address_postal_codestringtruenonePostal code
address_countrystringtruenoneCountry
return_address_idinteger(int32)truenoneID of return address to use
scheduleinteger(int32)falsenoneWhen to send letter (0/null=now)
template_usedinteger(int1)falsenoneWhether using our letter template. Flag value must be 1 for yes or 0 for no.
duplexinteger(int1)falsenoneWhether letter is duplex. Flag value must be 1 for yes or 0 for no.
colourinteger(int1)falsenoneWhether letter is in colour. Flag value must be 1 for yes or 0 for no.
priority_postinteger(int1)falsenoneWhether letter is priority. Flag value must be 1 for yes or 0 for no.
sourcestringfalsenoneSource being sent from

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
string
Bodyapplication/json
file_urlstring
Example: "https://clicksend-api-downloads-dev.s3.ap-southeast-2.amazonaws.com/_private/1DA3BD26-25F5-4B51-900D-C89FE0FCE355.pdf?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=XXXXXXXXXXXXXXXap-southeast-2%2Fs3%2Faws4_request&X-Amz-Date=20240229T053502Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Signature=76ed3e19d416acc7f4bafc00a848badad388104c23d333f16d1047309c743358"
template_usedinteger
duplexinteger
colourinteger
sourcestring
Example: "test"
recipientsArray of objects
Example: [{"address_name":"test","address_city":"test","address_state":"test","address_postal_code":"6000","address_country":"AU","address_line_1":"1 test street","return_address_id":"1154"}]
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \

     --header "Content-Type: application/json" \
     --data-binary "{
  \"file_url\": \"http://yourdomain.com/file.pdf\",
  \"template_used\": 1,
  \"colour\": 1,
  \"duplex\": 0,
  \"priority_post\": 0,
  \"recipients\": [
    {
      \"address_name\": \"My Home Address\",
      \"address_line_1\": \"Address 1\",
      \"address_line_2\": \"Address 2\",
      \"address_city\": \"CITY\",
      \"address_state\": \"State\",
      \"address_postal_code\": 123456,
      \"address_country\": \"AU\",
      \"return_address_id\": 1,
      \"custom_string\": \"Custom kn0ChLhwn6\",
      \"schedule\": 1449573604
    }
  ]
}" \
'https://rest.clicksend.com/v3/post/letters/price'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here are some results."
dataobject
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here are some results.",
  "data": {
    "total_price": 1.87,
    "total_cost": 1,
    "recipients": [ … ]
  }
}

Detect Address

Request

Detects address in uploaded file.

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.

Parameters

ParameterInTypeRequiredDescription
convertquerystringtruenone
contentbodystringtrueBase64-encoded file contents

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
Bodyapplication/json
object
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \
     --header "Content-Type: application/json" \
     --data-binary "{
    \"content\": \"Q29udGVudHMgb2YgZmlsZQ==\"
}" \
'https://rest.clicksend.com/v3/post/letters/detect-address'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here is your result."
dataobject
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here is your result.",
  "data": {
    "address_name": "John Doe",
    "address_line_1": "123 Main Street",
    "address_line_2": "",
    "address_city": "Perth",
    "address_state": "WA",
    "address_postal_code": "6000",
    "address_country": "AU"
  }
}

Cancel Scheduled Letter

Request

Cancel scheduled letter

Parameters

ParameterInTypeRequiredDescription
message_idquerystringtrueMessage ID of the scheduled letter that is to be cancelled.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Path
message_idstringrequired
Body

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Scheduled letter has been cancelled."
databoolean
Example: true
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Scheduled letter has been cancelled.",
  "data": true
}

View Letter History

Request

Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/post/letters/history'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here is your history."
dataobject
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here is your history.",
  "data": {
    "total": 2,
    "per_page": 15,
    "current_page": 1,
    "last_page": 1,
    "next_page_url": null,
    "prev_page_url": null,
    "from": 1,
    "to": 2,
    "data": [ … ]
  }
}

Export Letter History

Request

export letter history

Parameters

ParameterInTypeRequiredDescription
filenamequerystringtrueFilename to export to

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Query
filenamestring
Example: filename=Post_history.csv
qstring
order_bystring
Example: order_by=date_added:desc
date_fromstring
date_tostring
limitinteger
Example: limit=50000
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/post/letters/history/export?filename={filename}'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Download your file here."
dataobject
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Download your file here.",
  "data": {
    "url": "https://rest.clicksend.com/files/22D55AF9-6CF0-476D-A8B3-82A998FD2738?filename=export.csv"
  }
}