Skip to main content
POST
/
api
/
v1
/
letters
curl -X POST https://thepostalcompany.com/api/v1/letters \
  -H "Authorization: Bearer tpc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "Jane Doe",
    "address": {
      "street": "Keizersgracht",
      "number": "123",
      "postalcode": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL"
    },
    "content": "Dear Jane,\n\nThis is a letter sent via the API.\n\nBest regards"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "balance_cents": 1000
}

​
Create a Letter

Create a physical letter by providing recipient details, a validated address, and the letter content. By default, the letter is sent immediately. Set send to false to create a draft you can review and send later.

​
Request

​
recipient
string
Name of the recipient. Maximum 30 characters.
​
address
object
required
The recipient’s postal address.
​
content
string
required
The letter body text. Line breaks (\n) are preserved for formatting.
​
send
boolean
default:"true"
Whether to send the letter immediately. Set to false to create a draft. Drafts can be updated with PATCH /api/v1/letters/:id and sent with POST /api/v1/letters/:id/send.

​
Response

​
id
string
The unique letter ID.
​
status
string
The letter status — "processing" when sent immediately, "draft" when created as a draft.
​
balance_cents
integer
Your remaining balance in cents after this letter. Only present when send is true.

​
Examples

curl -X POST https://thepostalcompany.com/api/v1/letters \
  -H "Authorization: Bearer tpc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "Jane Doe",
    "address": {
      "street": "Keizersgracht",
      "number": "123",
      "postalcode": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL"
    },
    "content": "Dear Jane,\n\nThis is a letter sent via the API.\n\nBest regards"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "balance_cents": 1000
}

​
Error codes

StatusDescription
400Invalid request body — missing or invalid fields
401Missing, invalid, or revoked API key
402Insufficient balance to send the letter (only when send is true)
500Internal server error