Calculate Postcard Price

Send Postcard

Request

Send one or more postcards

Supported File Types

We support PDF, docx, doc, jpg, gif, png, and bmp. Contact us to add support for any other file type. If you're using docx, doc, jpg, gif, png, or bmp files, you'll need to convert the file first using our uploads endpoint with the querystring parameter ?convert=postcard. e.g. POST /uploads?convert=postcard. This will return a URL to the converted pdf file that can be used in the /post/postcards/send endpoint.

Postcard Specification Guide

Follow our Postcard specification guide to ensure correct sending and postcard template information.

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.

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

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.

Properties

Name	Type	Required	Restrictions	Description
file_urls	[string]	true	none	Postcard file URLs
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)

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_urlsArray of strings

Example: ["{{url}}"]

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_urls\":[
         \"https://s3-ap-southeast-2.amazonaws.com/clicksend-api-downloads/_public/_examples/a5_front.pdf\",
         \"https://s3-ap-southeast-2.amazonaws.com/clicksend-api-downloads/_public/_examples/a5_back.pdf\"
    ],
    \"recipients\":[
        {
            \"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\": \"Custom abc123\"
        }
    ]
}" \
'https://rest.clicksend.com/v3/post/postcards/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: "Postcard queued for delivery."

dataobject

Response

application/json

{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Postcard queued for delivery.",
  "data": {
    "total_price": 11,
    "total_count": 1,
    "queued_count": 1,
    "recipients": [ … ],
    "_currency": { … }
  }
}