Trigger a campaign send to handle- or profile-based recipients and read back per-send status.
openapi: 3.0.0
info:
title: Hightouch Campaigns API
description: Hightouch Public Rest API to access syncs, models, sources and destinations
version: 1.0.0
contact:
name: Hightouch
url: https://hightouch.com
x-harvested-from: https://api.hightouch.io/api/swagger.json
x-harvested-on: '2026-08-13'
x-source-document: openapi/_original/hightouch-api-openapi.json
servers:
- url: https://api.hightouch.com/api/v1
tags:
- name: Campaigns
paths:
/campaigns/{campaignId}/trigger:
post:
operationId: TriggerCampaign
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/StartCampaignResponse'
- $ref: '#/components/schemas/TriggerErrorResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
'401':
description: Unauthorized
'404':
description: Campaign not found
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'429':
description: Rate limited
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: 'Start an API-triggered campaign: send to the given recipients.'
summary: Trigger an API campaign send
security:
- bearerAuth: []
parameters:
- in: path
name: campaignId
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StartCampaignRequest'
tags:
- Campaigns
/campaigns/{campaignId}/sends/{sendId}:
get:
operationId: GetSendStatus
responses:
'200':
description: Ok
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/SendStatusResponse'
- $ref: '#/components/schemas/TriggerErrorResponse'
'401':
description: Unauthorized
'404':
description: Send not found
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerErrorResponse'
'422':
description: Validation Failed
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateErrorJSON'
'500':
description: Something went wrong
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
description: 'Get the delivery status of a single send by the `sendId` returned from the
start endpoint.'
summary: Get send delivery status
security:
- bearerAuth: []
parameters:
- in: path
name: campaignId
required: true
schema:
type: string
- in: path
name: sendId
required: true
schema:
type: string
tags:
- Campaigns
components:
schemas:
CampaignRecipient:
anyOf:
- $ref: '#/components/schemas/HandleCampaignRecipient'
- $ref: '#/components/schemas/ProfileCampaignRecipient'
description: 'A single send target. Provide either `handle` (inline delivery address) or
`id` (Personalization API profile ID), but not both.'
CampaignSendResult:
description: 'Per-recipient result returned synchronously after the trigger request.
Accepted recipients are queued for delivery; check the send status endpoint
for delivery confirmation.'
properties:
handle:
type: string
description: Delivery address of the recipient, present for inline (`handle`) recipients.
id:
type: string
description: 'Primary key of the recipient as configured on the Personalization API sync,
present for profile (`id`) recipients.'
status:
type: string
enum:
- accepted
- rejected
description: Whether this recipient was accepted for delivery or rejected at validation time.
sendId:
type: string
description: 'Unique identifier for this send, present when `status` is `"accepted"`.
Use with `GET /campaigns/{id}/sends/{sendId}` to poll for delivery status.'
reason:
type: string
enum:
- invalid_handle
- missing_variables
- invalid_id
- missing_handle_or_id
description: 'Reason for rejection, present when `status` is `"rejected"`.
- `invalid_handle` — the delivery address is not a valid email or phone number
- `missing_variables` — one or more required template variables are absent
- `invalid_id` — the profile ID is empty or missing
- `missing_handle_or_id` — the recipient has neither `handle` nor `id`'
missingVariables:
items:
type: string
type: array
description: 'Names of the required template variables absent from the recipient''s data,
present when `reason` is `"missing_variables"`.'
required:
- status
type: object
additionalProperties: false
HandleCampaignRecipient:
description: 'A recipient identified by their delivery address (email or phone number).
Personalization data is provided inline in the request.'
properties:
handle:
type: string
description: 'Delivery address for this recipient. Must be a valid email address for
email campaigns, or an E.164-formatted phone number for SMS campaigns.'
properties:
properties: {}
additionalProperties: {}
type: object
description: 'Per-recipient personalization properties. Keys must match the variable
names shown in the message editor. These are merged with the top-level
`properties` and take precedence when a key appears in both.'
type: object
additionalProperties: false
InternalServerError:
type: string
enum:
- Internal Server Error
nullable: false
ProfileCampaignRecipient:
description: A recipient identified by their Personalization API Cached profile ID.
properties:
id:
type: string
description: 'Primary key of the recipient as configured on the Personalization API sync.
The delivery address is resolved from the cache at send time.'
properties:
properties: {}
additionalProperties: {}
type: object
description: 'Per-recipient personalization overrides. Merged with the top-level
`properties` and the cached profile; these values take precedence when a
key appears in multiple sources.'
type: object
additionalProperties: false
SendStatusResponse:
description: Delivery status for a single send, returned by the send status endpoint.
properties:
status:
type: string
description: 'Current delivery status.
- `sent` — accepted by the provider; no delivery receipt yet
- `delivered` — confirmed delivered by the provider
- `bounced` — delivery failed with a bounce
- `failed` — delivery failed
- `dropped` — dropped before delivery (e.g. unsubscribed, suppressed, or enrichment failure);
see `reason`'
reason:
type: string
description: 'Additional explanation for why this send was dropped.
Only present when `status` is `"dropped"`.'
required:
- status
type: object
additionalProperties: false
StartCampaignRequest:
description: Request body for triggering an API campaign send.
properties:
properties:
properties: {}
additionalProperties: {}
type: object
description: 'Shared personalization properties applied to all recipients. Keys must
match the variable names shown in the message editor. Per-recipient
`properties` take precedence when a key appears in both.'
draft:
type: boolean
description: 'When `true`, sends the campaign even if it has not been activated.
Intended for test sends against draft campaigns only.'
default: 'false'
recipients:
items:
$ref: '#/components/schemas/CampaignRecipient'
type: array
description: 'List of recipients to send to. Each entry must include either a `handle`
(delivery address) or an `id` (Personalization API based profile ID).'
minItems: 1
maxItems: 100
required:
- recipients
type: object
additionalProperties: false
StartCampaignResponse:
description: 'Response body for a campaign trigger request. Results are returned in the
same order as the input `recipients` array.'
properties:
results:
items:
$ref: '#/components/schemas/CampaignSendResult'
type: array
description: 'Per-recipient outcomes. Accepted recipients are queued for delivery;
rejected recipients were not sent.'
required:
- results
type: object
additionalProperties: false
TriggerErrorResponse:
description: 'Body returned on a request-level failure (400/404/409/429) so the caller
knows why the request was rejected.'
properties:
error:
type: string
description: Human-readable description of why the request failed.
required:
- error
type: object
additionalProperties: false
ValidateErrorJSON:
properties:
message:
type: string
enum:
- Validation failed
nullable: false
details:
properties: {}
additionalProperties: {}
type: object
required:
- message
- details
type: object
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Bearer
security:
- bearerAuth: []