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.email`	string	Optional recipient email address for analytics and attribution.
`data.domain`	string	Optional recipient or account domain for analytics and attribution.
`data.address`	object	Recipient postal address.
`data.attachments`	array	Optional account-enabled PDF attachment overrides. Array order maps to the campaign's configured attachment slots.
`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.

Email and domain fields

Send recipient email and domain as first-class fields on the recipient object when you have them:

{
  "email": "ada@example.com",
  "domain": "example.com"
}

Scribeless stores email and domain separately from variables and uses them for analytics and attribution. Prefer these fields instead of putting email addresses, company domains, or source domains in variables.

Recipient attachments

Recipient attachments let an enabled integration provide a different PDF for each recipient in a one-time campaign. Recipient attachments are not available to all teams. Please get in touch to have this feature enabled on your account. Once enabled, Scribeless will configure the campaign's attachment slots and provide the approved upload workflow.

Send attachments on each recipient as an ordered array. Each non-null entry uses this schema:

{
  "attachments": [
    {
      "url": "teams/TEAM_ID/campaigns/CAMPAIGN_ID/attachments/RECIPIENT_PROOF.pdf"
    }
  ]
}

url is not an arbitrary public URL. It must be the path of a PDF already uploaded for the same Scribeless team and campaign through your approved attachment upload workflow. Remote https:// URLs and paths belonging to another team or campaign are rejected.

Array order selects the campaign attachment slot: the first item maps to slot 0, the second to slot 1, and so on. Use null to skip a slot while preserving later positions:

{
  "attachments": [
    null,
    {
      "url": "teams/TEAM_ID/campaigns/CAMPAIGN_ID/attachments/SECOND_PROOF.pdf"
    }
  ]
}

Omit attachments when the recipient does not override any campaign defaults. A required slot without either a recipient attachment or a configured campaign default fails validation.

Scribeless reads the PDF page count after upload. Attachment charges are then added based on your per-page or per-attachment pricing.

Test the complete upload and recipient-creation workflow with one non-sensitive PDF and one recipient before sending production traffic.

Variables and custom fields

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

{
  "variables": {
    "custom1": "This is a personalized first sentence",
    "custom2": "Thanks for being with us for one year",
    "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.",
      "email": "joe.blogs@example.com",
      "domain": "example.com",
      "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": "Thanks for being with us for one year"
      }
    }
  }'

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.",
        "email": "joe.blogs@example.com",
        "domain": "example.com",
        "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.",
        "email": "janet.blogs@example.com",
        "domain": "example.com",
        "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.",
    "email": "joe.blogs@example.com",
    "domain": "example.com",
    "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 one-time campaigns that require checkout, 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.
`403`	Recipient attachments are not enabled for the authenticated team.
`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.

Activate campaign

Activate an API-created recurring Scribeless campaign.

Fetch recipient

Get a Scribeless recipient by ID.