Tratta Docs

# Campaign Subscribers

A Campaign Subscriber represents a single email that should be sent. The subscriber row carries the recipient email, the linked Debt Account, and the variables that are used by the Email Template.

A subscriber is unique per (campaign + date + debt_account_external_id + email). Adding the same subscriber to the same campaign twice on the same day results in a validation error.

Emails are only sent during the window allowed by the Fair Debt Collection Practices Act (FDCPA). Tratta applies an additional 1-hour cut-off, meaning emails only go out between 08:00 and 20:00 in the customer's local timezone (based on their address). Anything not sent by 20:00 goes out the next day at 08:00. If the customer's timezone can't be determined, then a safety window is used that covers every possible timezone from New York to Honolulu.

# Create Campaign Subscribers

POST https://<org-uuid>.production.tratta.io/api/v1/email-campaigns/{campaign_id}/subscribers

curl https://<org-uuid>.production.tratta.io/api/v1/email-campaigns/{campaign_id}/subscribers \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -H "Content-Type: application/json" \
 -d '{
       "subscribers": [
         { "email": "alice@example.com", "debt_account_external_id": "123", "variables": { "customer_first_name": "Alice" } },
         { "email": "bob@example.com", "debt_account_external_id": "456", "variables": { "customer_first_name": "Bob" } }
       ]
     }'

Up to 100 subscribers can be created in a single call. The endpoint always returns 201 Created, even when some rows fail. Details are in the passed and failed arrays in the response.

# Parameters

subscribers required|array|min:1|max:100

Array of subscriber payloads. Each element accepts email, debt_account_external_id, and the optional variables object.

{
  "subscribers": [
    {
      "email": "alice@example.com",
      "debt_account_external_id": "123",
      "variables": { "customer_first_name": "Alice" }
    },
    {
      "email": "bob@example.com",
      "debt_account_external_id": "456",
      "variables": { "customer_first_name": "Bob" }
    }
  ]
}

# Returns

{
  "passed": [{
    "id": "uuid",
    "email": "string",
    "debt_account_external_id": "string",
    "status": "string",
    "status_reason": "string",
    "campaign_run_uuid": "uuid",
    "created_at": "timestamp"
  }],
  "failed": [{
    "index": "integer",
    "debt_account_external_id": "string",
    "reason": "string"
  }]
}

Each entry in failed includes the index of the offending row in the subscribers array.

# Failure reasons
reason Meaning
debt_account_not_found No debt account matched debt_account_external_id.
duplicate A subscriber already exists for this (campaign + date + debt_account_external_id + email).

← Bulk →