Skip to main content
POST
/
projects
/
add-recipients
/
{projectUuid}
Add recipients to a project
curl --request POST \
  --url https://www.postable.com/api/v1/projects/add-recipients/{projectUuid} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipients": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "address": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345",
      "country": "United States",
      "email": "john@example.com",
      "internal_id": "CUST-001"
    },
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "address": "456 Oak Ave",
      "apt": "Suite 100",
      "city": "Othertown",
      "state": "NY",
      "zip": "67890",
      "country": "United States",
      "override_message": "Custom message for Jane"
    }
  ]
}
'
{
  "data": {
    "message": "<string>",
    "contacts_updated": 123,
    "contacts_created": 123
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.postable.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Add one or more recipients to an existing project. Each recipient will be created as a contact in your address book and added to the project.

​
Behavior

  • If a recipient has an internal_id that matches an existing contact, that contact will be updated instead of creating a duplicate
  • Recipients without internal_id will always create new contacts
  • Use override_message and override_signoff to customize the card message for specific recipients
  • Use sender to set a per-recipient return address. When provided, the printed card shows this sender in the corner instead of your account-level return address. Omit it to use the account default.

​
Per-Recipient Sender (Return Address)

By default, every card prints your account’s return address in the corner. To make each card show its own individual sender, include a sender object on the recipient.
  • If sender is present, address, city, and country are required, and either name or company must be provided.
  • For United States addresses, state and a valid zip are also required.
  • Recipients without a sender continue to use the account-level return address.

​
Example: Adding Recipients with Custom Messages

{
  "recipients": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "address": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345",
      "country": "United States",
      "internal_id": "CUST-001"
    },
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "address": "456 Oak Ave",
      "apt": "Suite 100",
      "city": "Othertown",
      "state": "NY",
      "zip": "67890",
      "country": "United States",
      "override_message": "Dear Jane, wishing you a wonderful holiday season!",
      "override_signoff": "Best wishes, The Team"
    }
  ]
}

​
Example: Adding a Recipient with a Custom Sender

{
  "recipients": [
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "address": "456 Oak Ave",
      "city": "Othertown",
      "state": "NY",
      "zip": "67890",
      "country": "United States",
      "sender": {
        "name": "Alex Rivera",
        "company": "",
        "address": "789 Sender St",
        "apt": "Unit 4",
        "city": "Portland",
        "state": "OR",
        "zip": "97201",
        "country": "United States"
      }
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
projectUuid
string<uuid>
required

UUID of the project to add recipients to

Body

application/json
​
recipients
object[]
required

Response

Recipients added successfully

​
data
object