Letters (1.0.0)

Everything about Letters

Send Letter

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

Request

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

post/v3/post/letters/send

Request samples

application/json

{"file_url": "{{fileUrl}}",
"template_used": 1,
"colour": 0,
"duplex": 1,
"recipients": [{"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}}"
}
]
}

Response samples

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Letters queued for delivery.",
"data": {"recipients": [{"user_id": 1,
"subaccount_id": 1,
"message_id": "A00A1066-BBAE-432B-9B2D-E88969B12C46",
"address_name": "John Smith",
"address_line_1": "Address 1",
"address_line_2": "",
"address_city": "CITY",
"address_state": "State",
"address_postal_code": "123456",
"address_country": "AU",
"return_address_id": 1,
"custom_string": "kn0ChLhwn6",
"schedule": 1449573604,
"source": ".rest.v3",
"colour": 1,
"duplex": 0,
"post_pages": 7,
"post_price": "13.4200",
"priority_post": 0,
"date_added": 1459131623,
"status": "SUCCESS",
"_file_url": "http://yourdomain.com/file.pdf",
"_return_address": {"return_address_id": 1,
"user_id": 1,
"address_name": "John Smith",
"address_line_1": "Maritime Avenue",
"address_line_2": "",
"address_city": "Flynn",
"address_state": "WA",
"address_postal_code": 6302,
"address_country": "AU"
},
"_api_username": "my_api_username"
}
],
"_currency": {"currency_name_short": "AUD",
"currency_prefix_d": "$",
"currency_prefix_c": "c",
"currency_name_long": "Australian Dollars"
}
}
}

Calculate Letter Price

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

Request

header Parameters

Content-Type	string Example: application/json
	string

Request Body schema: application/json

object

Responses

200

Successful response

post/v3/post/letters/price

Request samples

application/json

{"file_url": "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_used": 0,
"duplex": 0,
"colour": 0,
"source": "test",
"recipients": [{"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"
}
]
}

Response samples

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Here are some results.",
"data": {"total_price": 1.87,
"total_cost": 1,
"recipients": [{"user_id": 1,
"subaccount_id": 1,
"message_id": "06FAD39C-78FD-4D2F-B606-9846D1979F35",
"address_name": "John Smith",
"address_line_1": "131",
"address_line_2": "Scheuvront Drive",
"address_city": "DENVER",
"address_state": "CO",
"address_postal_code": 80202,
"address_country": "AU",
"return_address_id": 1,
"schedule": 1449573604,
"post_pages": 3,
"post_price": "1.8700",
"priority_post": 0,
"date_added": 1449662203,
"status": "SUCCESS"
}
]
}
}

Detect Address

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

Request

header Parameters

Content-Type

string

Example: application/json

Request Body schema: application/json

object

Responses

200

Successful response

post/v3/post/letters/detect-address

Request samples

application/json

{"content": "Q29udGVudHMgb2YgZmlsZQ=="
}

Response samples

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

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

Request

path Parameters

message_id

required

string

Responses

200

Successful response

put/v3/post/letters/{message_id}/cancel

Response samples

application/json

{"http_code": 200,
"response_code": "SUCCESS",
"response_msg": "Scheduled letter has been cancelled.",
"data": true
}

View Letter History

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

Request

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/post/letters/history

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

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

Response samples

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": [{"user_id": 1,
"subaccount_id": 1,
"message_id": "06FAD39C-78FD-4D2F-B606-9846D1979F35",
"address_name": "John Smith",
"address_line_1": "131",
"address_line_2": "Scheuvront Drive",
"address_city": "DENVER",
"address_state": "CO",
"address_postal_code": 80202,
"address_country": "AU",
"return_address_id": 1,
"schedule": 1449573604,
"post_pages": 3,
"post_price": "1.8700",
"priority_post": 0,
"date_added": 1449662203,
"status": "SUCCESS"
}
]
}
}

Export Letter History

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

Request

query Parameters

filename	string Example: filename=Post_history.csv
q	string
order_by	string Example: order_by=date_added:desc
date_from	string
date_to	string
limit	integer Example: limit=50000

header Parameters

Content-Type

string

Example: application/json

Responses

200

Successful response

get/v3/post/letters/history/export

Request samples

curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

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

Response samples

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