Postcards (1.0.0)

Everything about Postcards

Send Postcard

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...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/post/postcards/send
Request samples
application/json
{
  • "file_urls": [
    ],
  • "recipients": [
    ]
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Postcard queued for delivery.",
  • "data": {
    }
}

Calculate Postcard Price

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

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...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/post/postcards/price
Request samples
application/json
{
  • "file_urls": [
    ],
  • "recipients": [
    ]
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here is some pricing.",
  • "data": {
    }
}

Cancel Scheduled Postcard

Cancel scheduled postcard

Parameters

Parameter In Type Required Description
message_id query string true Message 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...
Request
path Parameters
message_id
required
string
Responses
200

Successful response

put/v3/post/postcards/{message_id}/cancel
Request samples 
  curl --include \
         --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
         --request PUT \

    'https://rest.clicksend.com/v3/post/postcards/{message_id}/cancel'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Scheduled postcard has been cancelled.",
  • "data": true
}

View Postcard History

Retrieve the history of postcards sent or scheduled

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/postcards/history
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/post/postcards/history'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here is your history.",
  • "data": {
    }
}

Export Postcard History

Export postcard history to a CSV file

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
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/post/postcards/history/export
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/post/postcards/export?filename={filename}'
Response samples
application/json
{}
Copyright © ClickSend 2024. All right reserved.