Post
/
Postcards
/
Export Postcard History

Postcards

Everything about Postcards

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

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

NameTypeRequiredRestrictionsDescription
file_urls[string]truenonePostcard file URLs
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)

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

Calculate Postcard Price

Request

Calculate price for sending one or more postcards

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

Properties

NameTypeRequiredRestrictionsDescription
file_urls[string]truenonePostcard file URLs
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)

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_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\",
            \"custom_string\":\"Custom abc123\",
            \"return_address_id\":1
        }
    ]
}" \
'https://rest.clicksend.com/v3/post/postcards/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 is some pricing."
dataobject
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Here is some pricing.",
  "data": {
    "total_price": 11,
    "total_count": 1,
    "queued_count": 1,
    "recipients": [ … ],
    "_currency": { … }
  }
}

Cancel Scheduled Postcard

Request

Cancel scheduled postcard

Parameters

ParameterInTypeRequiredDescription
message_idquerystringtrueMessage ID of the scheduled postcard 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
  curl --include \
         --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
         --request PUT \

    'https://rest.clicksend.com/v3/post/postcards/{message_id}/cancel'

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 postcard has been cancelled."
databoolean
Example: true
Response
application/json
{
  "http_code": 200,
  "response_code": "SUCCESS",
  "response_msg": "Scheduled postcard has been cancelled.",
  "data": true
}

View Postcard History

Request

Retrieve the history of postcards sent or scheduled

Parameters

ParameterInTypeRequiredDescription
pagequeryinteger(int32)falsePage number
limitqueryinteger(int32)falseNumber of records per page

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

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/post/postcards/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 Postcard History

Request

Export postcard history to a CSV file

Parameters

ParameterInTypeRequiredDescription
filenamequerystringtrueFilename to export to

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

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/post/postcards/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/705F80D0-D044-4F85-8617-081988B398E5?filename=myexport.csv"
  }
}