Recipients

Create recipients

Create one or more recipients for a Scribeless campaign.

Create one or more recipients for an existing Scribeless campaign.

POST https://platform.scribeless.co/api/recipients

You must create the campaign first. Use the campaign ID as campaignId in the request body.

Headers

Content-Type: application/json
X-API-Key: YOUR_API_KEY

Request body

Field	Type	Description
`campaignId`	string	Existing Scribeless campaign ID.
`data`	object or array	One recipient object, or an array of recipient objects.
`data.title`	string	Optional recipient title.
`data.firstName`	string	Recipient first name.
`data.lastName`	string	Recipient last name.
`data.company`	string	Optional company name.
`data.address`	object	Recipient postal address.
`data.variables`	object	Optional custom variables for campaign personalization.
`data.variables.externalId`	string or number	Optional external system ID for this recipient.

Address fields

Send recipient addresses as a nested address object:

Field	Required	Description
`address.address1`	Usually yes	First address line. Required for mailed campaigns.
`address.address2`	No	Second address line.
`address.address3`	No	Third address line.
`address.city`	Usually yes	City, town, or locality.
`address.state`	Conditional	State or region. Required for countries such as the US and Canada.
`address.postalCode`	Conditional	Postal or ZIP code, where used by the destination country.
`address.country`	Usually yes	Two-letter country code, for example `GB` or `US`.

Campaign configuration determines which fields are required. For mailed campaigns, provide a complete postal address. Names and campaign variables still need to match the campaign setup.

Variables and custom fields

Use variables for campaign personalization values that are not standard name, company, or address fields.

{
  "variables": {
    "custom1": "This is a personalized first sentence",
    "custom2": "www.scribeless.co",
    "voucherCode": "SPRING-25"
  }
}

Keep variable names consistent with the campaign template. Send strings for values that will be rendered into handwritten copy.

External IDs

If your integration has its own stable ID for the recipient, customer, order, lead, or source record, send it as variables.externalId.

{
  "variables": {
    "externalId": "order_12345",
    "custom1": "This is a personalized first sentence"
  }
}

externalId is stored with the recipient and returned when you fetch the recipient later. It must be sent inside variables; a top-level externalId field is ignored.

For teams with external ID upsert enabled, Scribeless can use variables.externalId to update an existing ready recipient in the same ready recurring campaign instead of creating a duplicate. This behaviour depends on your account and campaign setup, so treat externalId as an external reference unless Scribeless has confirmed upsert is enabled for your workflow.

Create one recipient

curl --request POST 'https://platform.scribeless.co/api/recipients' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "campaignId": "CAMPAIGN_ID",
    "data": {
      "title": "Mr",
      "firstName": "Joe",
      "lastName": "Blogs",
      "company": "Blogs Inc.",
      "address": {
        "address1": "123 Blogs St",
        "address2": "Unit 4",
        "address3": "",
        "city": "Bristol",
        "state": "Bristol",
        "postalCode": "AB123CD",
        "country": "GB"
      },
      "variables": {
        "custom1": "This is a personalized first sentence",
        "custom2": "www.scribeless.co"
      }
    }
  }'

Create multiple recipients

curl --request POST 'https://platform.scribeless.co/api/recipients' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{
    "campaignId": "CAMPAIGN_ID",
    "data": [
      {
        "title": "Mr",
        "firstName": "Joe",
        "lastName": "Blogs",
        "company": "Blogs Inc.",
        "address": {
          "address1": "123 Blogs St",
          "city": "Bristol",
          "state": "Bristol",
          "postalCode": "AB123CD",
          "country": "GB"
        },
        "variables": {
          "custom1": "Thanks for being with us for one year"
        }
      },
      {
        "title": "Mrs",
        "firstName": "Janet",
        "lastName": "Blogs",
        "company": "Blogs Inc.",
        "address": {
          "address1": "123 Blogs St",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "12345",
          "country": "US"
        },
        "variables": {
          "custom1": "Your order has shipped"
        }
      }
    ]
  }'

Successful response

Successful requests return an array of the created or updated recipient records.

[
  {
    "id": "RECIPIENT_ID",
    "title": "Mr",
    "first_name": "Joe",
    "last_name": "Blogs",
    "company": "Blogs Inc.",
    "address1": "123 Blogs St",
    "address2": "Unit 4",
    "address3": "",
    "city": "Bristol",
    "state": "Bristol",
    "postal_code": "AB123CD",
    "country": "GB",
    "region": null,
    "variables": {
      "custom1": "This is a personalized first sentence",
      "custom2": "www.scribeless.co"
    },
    "created_at": "2026-01-01T10:00:00.000000+00:00",
    "updated_at": "2026-01-01T10:00:00.000000+00:00",
    "team_id": "TEAM_ID",
    "campaign_id": "CAMPAIGN_ID",
    "status": "pending"
  }
]

Treat any non-2xx response as failed and inspect the response body for message and any structured data.

You can fetch an individual recipient later with GET /api/recipients/{recipientId}. Once Scribeless has rendered the recipient, use GET /api/recipients/{recipientId}/preview to download a PNG preview.

For approved partner invoice-billed one-time campaigns, call POST /api/recipients/checkout after creating recipients. If a one-time campaign has already been paid or finalized, create a new campaign for the next send instead of adding more recipients.

Error examples

Missing or invalid API key:

{
  "error": true,
  "url": "https://platform.scribeless.co/api/recipients",
  "statusCode": 401,
  "statusMessage": "Server Error",
  "message": "Invalid authentication token."
}

Invalid recipient field:

{
  "error": true,
  "url": "https://platform.scribeless.co/api/recipients",
  "statusCode": 400,
  "statusMessage": "Server Error",
  "message": "Validation error",
  "data": {
    "_errors": [],
    "data": {
      "_errors": [
        "Expected array, received object",
        "Expected array, received object"
      ],
      "address": {
        "_errors": [
          "Required",
          "Required"
        ]
      },
      "firstName": {
        "_errors": [
          "Required"
        ]
      }
    }
  }
}

Invalid campaign state:

{
  "error": true,
  "url": "https://platform.scribeless.co/api/recipients",
  "statusCode": 400,
  "statusMessage": "Server Error",
  "message": "Failed to create recipients"
}

Status codes

Common status codes:

Status	Meaning
`2xx`	Recipient request accepted.
`400`	Missing or invalid request data.
`401`	Missing, malformed, invalid, or unauthorized API key or campaign/recipient action.
`503`	Temporary service issue. Retry later or contact support if it persists.

Testing and billing

Use a testing campaign and one non-sensitive recipient before turning on an automation. Testing recipients should not be treated as live mail. Live recipient creation can create billable usage according to the campaign product and delivery settings.

Fetch campaign

Get a Scribeless campaign by ID.

Fetch recipient

Get a Scribeless recipient by ID.