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
}

​
Send a Letter

Send a physical letter by providing recipient details, a validated address, and the letter content. The letter is queued for printing and postal delivery.

​
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.

​
Response

​
id
string
The unique letter ID. Use this for tracking.
​
status
string
The letter status. Will be "processing" on success.
​
balance_cents
integer
Your remaining balance in cents after this letter.

​
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
500Internal server error