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": [
    ]
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Letters queued for delivery.",
  • "data": {
    }
}

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
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are some results.",
  • "data": {
    }
}

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

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

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
{}
Copyright © ClickSend 2024. All right reserved.