Outreach

Every call needs Authorization: Bearer <key>. 7 calls:

• List outreach campaigns, newest first: GET /v1/outreach
• Create a draft campaign: POST /v1/outreach
• Get a campaign with its sending capacity: GET /v1/outreach/:id
• Edit a draft, or pause or resume a campaign: PATCH /v1/outreach/:id
• Cancel a campaign: POST /v1/outreach/:id/cancel
• Schedule a draft campaign: POST /v1/outreach/:id/schedule
• List a campaign's recipients and where each message is: GET /v1/outreach/:id/sends

List outreach campaigns, newest first

GET /v1/outreach

Query parameters

Name	Type	Required	Description
limit	integer	No	From 1 to 100. Default 50.
cursor	string	No	Opaque cursor from next_cursor. Up to 512 characters.
status	enum	No	One of: draft, scheduled, live, paused, completed, cancelled.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
data	object[]
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].finished_at	string (date-time) or null	ISO 8601 timestamp.
data[].id	string (uuid)
data[].kind	enum	One of: one_off, sequence.
data[].name	string
data[].per_line_throttle	integer or null	From 1 to 9007199254740991.
data[].pool_id	string or null	Pool id (pool_...).
data[].recipients	integer	From 0 to 9007199254740991.
data[].schedule_at	string (date-time) or null	ISO 8601 timestamp.
data[].segment_id	string (uuid) or null
data[].started_at	string (date-time) or null	ISO 8601 timestamp.
data[].stats	object
data[].status	enum	One of: draft, scheduled, live, paused, completed, cancelled.
data[].steps	object[]
data[].steps[].delay_hours	integer	From 1 to 720.
data[].steps[].stop_on_reply	boolean	Default true.
data[].steps[].template	string	Up to 2000 characters.
data[].template	string
data[].updated_at	string (date-time)	ISO 8601 timestamp.
next_cursor	string or null	Pass as cursor to get the next page; null at the end.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Create a draft campaign

POST /v1/outreach

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
kind	enum	No	One of: one_off, sequence. Default "one_off".
name	string	Yes	Up to 120 characters.
per_line_throttle	integer	No	Campaign messages per hour for each sending line, applied across the pool: at most lines × this an hour, and one line may carry more than its share. The governor still caps each line. From 1 to 50.
pool_id	string	No	Pool id (pool_...).
segment_id	string (uuid)	Yes
steps	object[]	No	Up to 10 items.
steps[].delay_hours	integer	Yes	From 1 to 720.
steps[].stop_on_reply	boolean	No	Default true.
steps[].template	string	Yes	Up to 2000 characters.
template	string	Yes	Up to 2000 characters.

Response 201

Field	Type	Description
created_at	string (date-time)	ISO 8601 timestamp.
finished_at	string (date-time) or null	ISO 8601 timestamp.
id	string (uuid)
kind	enum	One of: one_off, sequence.
name	string
per_line_throttle	integer or null	From 1 to 9007199254740991.
pool_id	string or null	Pool id (pool_...).
recipients	integer	From 0 to 9007199254740991.
schedule_at	string (date-time) or null	ISO 8601 timestamp.
segment_id	string (uuid) or null
started_at	string (date-time) or null	ISO 8601 timestamp.
stats	object
status	enum	One of: draft, scheduled, live, paused, completed, cancelled.
steps	object[]
steps[].delay_hours	integer	From 1 to 720.
steps[].stop_on_reply	boolean	Default true.
steps[].template	string	Up to 2000 characters.
template	string
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Get a campaign with its sending capacity

GET /v1/outreach/:id

Capacity is what the campaign's lines can carry now: lines, new contacts left today after messages already waiting, the hourly ceiling and a rough finish time.

Path parameters

Name	Type	Required	Description
id	string (uuid)	Yes

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
capacity	object
capacity.estimated_finish_at	string (date-time) or null	ISO 8601 timestamp.
capacity.lines	integer	From 0 to 9007199254740991.
capacity.new_contacts_left_today	integer	From 0 to 9007199254740991.
capacity.per_hour	integer	From 0 to 9007199254740991.
capacity.remaining	integer	From 0 to 9007199254740991.
created_at	string (date-time)	ISO 8601 timestamp.
finished_at	string (date-time) or null	ISO 8601 timestamp.
id	string (uuid)
kind	enum	One of: one_off, sequence.
name	string
per_line_throttle	integer or null	From 1 to 9007199254740991.
pool_id	string or null	Pool id (pool_...).
recipients	integer	From 0 to 9007199254740991.
schedule_at	string (date-time) or null	ISO 8601 timestamp.
segment_id	string (uuid) or null
started_at	string (date-time) or null	ISO 8601 timestamp.
stats	object
status	enum	One of: draft, scheduled, live, paused, completed, cancelled.
steps	object[]
steps[].delay_hours	integer	From 1 to 720.
steps[].stop_on_reply	boolean	Default true.
steps[].template	string	Up to 2000 characters.
template	string
updated_at	string (date-time)	ISO 8601 timestamp.
variables	string[]

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Edit a draft, or pause or resume a campaign

PATCH /v1/outreach/:id

Content changes only while the campaign is a draft. status: paused stops releasing messages (already-queued ones still go out); status: live resumes a paused campaign.

Path parameters

Name	Type	Required	Description
id	string (uuid)	Yes

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
name	string	No	Up to 120 characters.
per_line_throttle	integer or null	No	Campaign messages per hour for each sending line, applied across the pool: at most lines × this an hour, and one line may carry more than its share. The governor still caps each line. From 1 to 50.
pool_id	string or null	No	Pool id (pool_...).
segment_id	string (uuid)	No
status	enum	No	One of: paused, live.
steps	object[]	No	Up to 10 items.
steps[].delay_hours	integer	Yes	From 1 to 720.
steps[].stop_on_reply	boolean	No	Default true.
steps[].template	string	Yes	Up to 2000 characters.
template	string	No	Up to 2000 characters.

Response 200

Field	Type	Description
created_at	string (date-time)	ISO 8601 timestamp.
finished_at	string (date-time) or null	ISO 8601 timestamp.
id	string (uuid)
kind	enum	One of: one_off, sequence.
name	string
per_line_throttle	integer or null	From 1 to 9007199254740991.
pool_id	string or null	Pool id (pool_...).
recipients	integer	From 0 to 9007199254740991.
schedule_at	string (date-time) or null	ISO 8601 timestamp.
segment_id	string (uuid) or null
started_at	string (date-time) or null	ISO 8601 timestamp.
stats	object
status	enum	One of: draft, scheduled, live, paused, completed, cancelled.
steps	object[]
steps[].delay_hours	integer	From 1 to 720.
steps[].stop_on_reply	boolean	Default true.
steps[].template	string	Up to 2000 characters.
template	string
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Cancel a campaign

POST /v1/outreach/:id/cancel

Nothing more is released: unsent messages are skipped. Messages already queued still go out. Allowed while the organisation is paused.

Path parameters

Name	Type	Required	Description
id	string (uuid)	Yes

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Response 200

Field	Type	Description
created_at	string (date-time)	ISO 8601 timestamp.
finished_at	string (date-time) or null	ISO 8601 timestamp.
id	string (uuid)
kind	enum	One of: one_off, sequence.
name	string
per_line_throttle	integer or null	From 1 to 9007199254740991.
pool_id	string or null	Pool id (pool_...).
recipients	integer	From 0 to 9007199254740991.
schedule_at	string (date-time) or null	ISO 8601 timestamp.
segment_id	string (uuid) or null
started_at	string (date-time) or null	ISO 8601 timestamp.
stats	object
status	enum	One of: draft, scheduled, live, paused, completed, cancelled.
steps	object[]
steps[].delay_hours	integer	From 1 to 720.
steps[].stop_on_reply	boolean	Default true.
steps[].template	string	Up to 2000 characters.
template	string
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Schedule a draft campaign

POST /v1/outreach/:id/schedule

Fixes the recipients: the segment's contacts now, less anyone opted out. Refused when a template has no variables or would send the same text to more people than a line may send it in a day, or breaks the rules for texts to people who haven't replied yet: links, phone numbers, emails, length and number of messages. The worker then releases messages through the governor.

Path parameters

Name	Type	Required	Description
id	string (uuid)	Yes

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.
idempotency-key	string	No	Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters.

Request body

Field	Type	Required	Description
schedule_at	string (date-time)	No	Omit to start now.

Response 200

Field	Type	Description
created_at	string (date-time)	ISO 8601 timestamp.
finished_at	string (date-time) or null	ISO 8601 timestamp.
id	string (uuid)
kind	enum	One of: one_off, sequence.
name	string
per_line_throttle	integer or null	From 1 to 9007199254740991.
pool_id	string or null	Pool id (pool_...).
recipients	integer	From 0 to 9007199254740991.
schedule_at	string (date-time) or null	ISO 8601 timestamp.
segment_id	string (uuid) or null
started_at	string (date-time) or null	ISO 8601 timestamp.
stats	object
status	enum	One of: draft, scheduled, live, paused, completed, cancelled.
steps	object[]
steps[].delay_hours	integer	From 1 to 720.
steps[].stop_on_reply	boolean	Default true.
steps[].template	string	Up to 2000 characters.
template	string
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

List a campaign's recipients and where each message is

GET /v1/outreach/:id/sends

Path parameters

Name	Type	Required	Description
id	string (uuid)	Yes

Query parameters

Name	Type	Required	Description
limit	integer	No	From 1 to 100. Default 50.
cursor	string	No	Opaque cursor from next_cursor. Up to 512 characters.
status	enum	No	One of: pending, queued, sent, delivered, replied, failed, skipped.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Response 200

Field	Type	Description
data	object[]
data[].contact_id	string	Contact id (ctc_...).
data[].contact_name	string or null
data[].error_code	string or null
data[].id	string (uuid)
data[].line_id	string or null	Line id (ln_...).
data[].message_id	string or null	Message id (msg_...).
data[].phone	string
data[].scheduled_for	string (date-time) or null	ISO 8601 timestamp.
data[].status	enum	One of: pending, queued, sent, delivered, replied, failed, skipped.
data[].step	integer	From 0 to 9007199254740991.
data[].updated_at	string (date-time)	ISO 8601 timestamp.
next_cursor	string or null	Pass as cursor to get the next page; null at the end.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.