Letters

Post

Everything about Letters

We're no longer offering Post to new customers. If you're looking to reach people quickly, our SMS platform might be worth looking into.

Download OpenAPI description

letters.json

letters.yaml

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

Name	Type	Required	Restrictions	Description
file_url	string	true	none	URL of file to send
address_name	string	true	none	Name of address
address_line_1	string	true	none	First line of address
address_line_2	string	true	none	Second line of address
address_city	string	true	none	City
address_state	string	true	none	State
address_postal_code	string	true	none	Postal code
address_country	string	true	none	Country
return_address_id	integer(int32)	true	none	ID of return address to use
schedule	integer(int32)	false	none	When to send letter (0/null=now)
template_used	integer(int1)	false	none	Whether using our letter template. Flag value must be 1 for yes or 0 for no.
duplex	integer(int1)	false	none	Whether letter is duplex. Flag value must be 1 for yes or 0 for no.
colour	integer(int1)	false	none	Whether letter is in colour. Flag value must be 1 for yes or 0 for no.
priority_post	integer(int1)	false	none	Whether letter is priority, Flag value must be 1 for yes or 0 for no.
source	string	false	none	Source being sent from

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

This endpoint requires authentication,more info...

Security

basicAuth

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

Name	Type	Required	Restrictions	Description
file_url	string	true	none	URL of file to send
address_name	string	true	none	Name of address
address_line_1	string	true	none	First line of address
address_line_2	string	true	none	Second line of address
address_city	string	true	none	City
address_state	string	true	none	State
address_postal_code	string	true	none	Postal code
address_country	string	true	none	Country
return_address_id	integer(int32)	true	none	ID of return address to use
schedule	integer(int32)	false	none	When to send letter (0/null=now)
template_used	integer(int1)	false	none	Whether using our letter template. Flag value must be 1 for yes or 0 for no.
duplex	integer(int1)	false	none	Whether letter is duplex. Flag value must be 1 for yes or 0 for no.
colour	integer(int1)	false	none	Whether letter is in colour. Flag value must be 1 for yes or 0 for no.
priority_post	integer(int1)	false	none	Whether letter is priority. Flag value must be 1 for yes or 0 for no.
source	string	false	none	Source being sent from

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

This endpoint requires authentication,more info...

Security

basicAuth

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

Parameter	In	Type	Required	Description
convert	query	string	true	none
content	body	string	true	Base64-encoded file contents

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

This endpoint requires authentication,more info...

Security

basicAuth

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

Parameter	In	Type	Required	Description
message_id	query	string	true	Message 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

Get all letter history

Parameters

Parameter	In	Type	Required	Description
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number of records per page

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

This endpoint requires authentication,more info...

Security

basicAuth

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

Parameter	In	Type	Required	Description
filename	query	string	true	Filename to export to

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

This endpoint requires authentication,more info...

Security

basicAuth

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"
  }
}

Letters

Send Letter

Request

Send letter

Supported File Types

Letter Specification Guide

Letter File Options

Use existing URL

Upload File to Our Server

Properties

Responses

Was this helpful?

Calculate Letter Price

Request

Properties

Responses

Was this helpful?

Detect Address

Request

Parameters

Responses

Was this helpful?

Cancel Scheduled Letter

Request

Parameters

Responses

Was this helpful?

View Letter History

Request

Parameters

Responses

Was this helpful?

Export Letter History

Request

Parameters

Responses

Was this helpful?

Letters

Send Letter

RequestExpand all

Send letter

Supported File Types

Letter Specification Guide

Letter File Options

Use existing URL

Upload File to Our Server

Properties

Responses

Was this helpful?

Calculate Letter Price

RequestExpand all

Properties

Responses

Was this helpful?

Detect Address

Request

Parameters

Responses

Was this helpful?

Cancel Scheduled Letter

Request

Parameters

Responses

Was this helpful?

View Letter History

Request

Parameters

Responses

Was this helpful?

Export Letter History

Request

Parameters

Responses

Was this helpful?

Request

Request