Skip to main content
POST
Create a letter

Authorizations

Authorization
string
header
required

API Key authentication. Use "Bearer YOUR_API_KEY".

Body

application/json
recipient
object
required

Who the letter is addressed to.

address_position
enum<string>

Which side of page 1 the recipient address window is printed on.

Available options:
left,
right
auto_send
boolean
default:false

If true, the letter is printed and posted immediately after creation.

blocks
object[]

Content blocks. Required when template is omitted; otherwise copied from the template.

delivery_product
enum<string>
default:standard

Postage product used when the letter is sent.

Available options:
standard,
premium
name
string

A name for this letter. Defaults to the template name.

template
string

The ID of a letter template to copy content from.

variables
object

Values for the template custom variables, keyed by variable key.

Response

200 - application/json

Returns the letter object if the request succeeded.

id
string
required

Unique identifier for the object.

created
number
required

Time at which the object was created. Measured in seconds since the Unix epoch.

object
enum<string>
required
Available options:
letter
address_position
enum<string>
required

Which side of page 1 the recipient address window is printed on.

Available options:
left,
right
blocks
object[]
required

Content blocks that will be printed. Snapshotted from the template when one is used.

customer
required

The customer this letter is addressed to, when recipient_type is customer.

delivery_error
string | null
required

Why sending failed, if status is failed.

delivery_product
enum<string>
required

Postage product used when the letter is sent.

Available options:
standard,
premium
name
string | null
required

A name for this letter. Defaults to the template name.

owner
required

The owner this letter is addressed to, when recipient_type is owner.

page_count
integer | null
required

Number of PDF pages in the letter, set when it is sent. Extra pages beyond the first are billed separately.

recipient_type
enum<string>
required

Who the letter is addressed to.

Available options:
customer,
owner
sent_at
number | null
required

Time at which the letter was submitted to for printing. Measured in seconds since the Unix epoch.

status
enum<string>
required

The current status of the letter.

Available options:
draft,
sending,
sent,
canceled,
failed
template
required

The letter template this letter was created from, if any.

tracking_number
string | null
required

Postal tracking number, when one is available.

variables
object
required

Values for the template custom variables, keyed by variable key.

account
string

The account that the object belongs to. Only returned if the request is made with a valid Yorlet-Context header.

deleted
boolean
default:false

Only returned if the object has been deleted.