API reference

Outreach

10 operations. REST https://dev.tlntconnect.com/api/v1

GET/api/v1/outreach/templatesThe workspace's active outreach email templates, newest first, with how often each was used.

Every active outreach template in this workspace, as the app's Templates tab lists them: id, name, subject, body_html, body_text, variables, category (cold_intro, follow_up, social_proof, custom), created_at, updated_at and times_used (outreach emails sent with it). Templates carry merge fields — {{creator_first_name}}, {{display_name}}, {{brand_name}}, {{sender_name}}, {{tiktok_username}}, {{ig_username}}, {{email}}, {{total_reach}}, {{total_reach_formatted}}, {{platform}}, {{niche}} — that a send fills per recipient. Requires outreach:read.

Scopes
outreach:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
POST/api/v1/outreach/templatesCreate an outreach email template (name, subject, HTML or plain-text body, category).

Creates an active outreach template in this workspace, owned by the key's member. Send name, subject and body_html or body_text (or both): HTML goes through the app's email sanitizer (400 invalid_input when nothing is left); a plain-text body alone becomes escaped HTML paragraphs, and an HTML body alone gets its text version derived. category defaults to cold_intro. Answers 201 with the template. Requires outreach:write and an admin or manager member.

Scopes
outreach:write
Members
admin, manager
Idempotency-Key
optional
Rate weight
1

Input

Idempotency-Key headerstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
name body, requiredstring — Template name.
subject body, requiredstring — Subject line; may carry merge fields.
body_html bodystring — HTML body. Cleaned by the app's email sanitizer (scripts, styles and unsafe attributes are removed).
body_text bodystring — Plain-text body. Given alone, the HTML body is rendered from it (paragraphs, escaped).
category body"cold_intro" | "follow_up" | "social_proof" | "custom" — cold_intro (default), follow_up, social_proof or custom.
variables bodyarray of string — Merge fields the template uses (informational).

Responses

201Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
409idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After)
500internal_error / idempotent_replay_of_failure
503service_unavailable
GET/api/v1/outreach/templates/{template_id}One active outreach template: subject, HTML and text bodies, category and version.

One active outreach template of this workspace. Another workspace's id, or a deleted template, is 404. updated_at is the version to pass as expected_updated_at when you update or delete it. Requires outreach:read.

Scopes
outreach:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1

Input

template_id path, requiredstring (uuid) — Outreach template id in this workspace.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
PATCH/api/v1/outreach/templates/{template_id}Change an outreach template's name, subject, body, category or variables.

Updates an active template of this workspace. Send at least one of name, subject, body_html, body_text, category, variables (400 invalid_input otherwise). body_html is sanitized; body_text alone replaces the body (its HTML is rendered from it). Optional expected_updated_at: a template changed since you read it is 409 stale_target. Another workspace's id, or a deleted template, is 404. Requires outreach:write and an admin or manager member.

Scopes
outreach:write
Members
admin, manager
Idempotency-Key
optional
Rate weight
1

Input

template_id path, requiredstring (uuid) — Outreach template id in this workspace.
Idempotency-Key headerstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
expected_updated_at bodystring — The record's updated_at as you last read it. Optional: when given, a record changed since then is refused (409 stale_target). In a query string, URL-encode it (+ as %2B).
name bodystring — Template name.
subject bodystring — Subject line; may carry merge fields.
body_html bodystring — HTML body. Cleaned by the app's email sanitizer (scripts, styles and unsafe attributes are removed).
body_text bodystring — Plain-text body. Given alone, the HTML body is rendered from it (paragraphs, escaped).
category body"cold_intro" | "follow_up" | "social_proof" | "custom" — cold_intro (default), follow_up, social_proof or custom.
variables bodyarray of string — Merge fields the template uses (informational).

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
409stale_target / idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After)
500internal_error / idempotent_replay_of_failure
503service_unavailable
DELETE/api/v1/outreach/templates/{template_id}Delete an outreach template. Runs directly within the daily delete cap.

Deletes (retires) one outreach template, exactly as the app's delete does: it stops being offered, while the outreach history and stats that name it keep it. A `delete`-class action: it deletes at once and answers 200 { status: "deleted" }, within the credential's daily delete cap (429 daily_delete_cap_reached past it). Optional expected_updated_at: a template changed since you read it is 409 stale_target. Another workspace's id, or a deleted template, is 404. Requires the outreach:read and delete scopes, an Idempotency-Key, and an admin or manager member.

Scopes
outreach:read + delete
Members
admin, manager
Runs
Directly; delete class
Idempotency-Key
required
Rate weight
1

Input

template_id path, requiredstring (uuid) — Outreach template id in this workspace.
expected_updated_at querystring — The record's updated_at as you last read it. Optional: when given, a record changed since then is refused (409 stale_target). In a query string, URL-encode it (+ as %2B).
Idempotency-Key header, requiredstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.

Responses

200Success
202pending_approval — a retry with the same Idempotency-Key found this request's action still open (still running, or queued before in-app approval was removed); poll it
400invalid_input / invalid_json / invalid_id / idempotency_key_required
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
409stale_target / idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After) / daily_delete_cap_reached
500internal_error / idempotent_replay_of_failure
503service_unavailable
POST/api/v1/outreach/previewRender the email one recipient would get from a template and/or subject + body, exactly as a send would. Sends nothing.

Renders the subject, HTML body and text body ONE recipient would receive — the same rendering a send uses (the request's fields over the template's, merge fields from the roster creator or, for an address, their fallbacks). Name exactly one of creator_id (a roster creator of this workspace; another workspace's id is 404) or recipient_email. Nothing is sent or saved. Merged creator names and profile fields are text authored outside the agency: subject, body_html, body_text and to_name are wrapped as untrusted content. Requires outreach:write.

Scopes
outreach:write
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1
Untrusted fields
data.to_name data.subject data.body_html data.body_text

Input

creator_id bodystring (uuid) — A roster creator in this workspace.
recipient_email bodystring — A literal address.
template_id bodystring (uuid) — A template to start from: its subject and body fill whatever you leave out.
subject bodystring — Subject line; merge fields are filled per recipient.
body_text bodystring — Plain-text body (escaped into HTML paragraphs); merge fields are filled per recipient.
body_html bodystring — HTML body instead of body_text, cleaned by the app's email sanitizer.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
POST/api/v1/outreach/sendEmail up to 100 roster creators or addresses from a mailbox the key's member can send from. Sends directly within the daily recipient cap.

Sends one outreach email per recipient — the same send as the app's composer (validation, merge fields, the mailbox's sender permission, outreach history, inbox thread). Not metered: no credits are charged. A creator is marked contacted only from an earlier pipeline stage (one who replied or signed up keeps their stage). Recipients: creator_ids (roster creators of THIS workspace — another workspace's id is 404) and/or recipient_emails (any valid address; one that belongs to roster creators is sent to each of them), at most 100 in all and at most 100 messages once addresses are resolved (400 invalid_input). An address on the workspace's outreach opt-out list is never sent: it is reported as skipped with error "opted out" (and listed as skipped on an approval), and a request whose every recipient opted out is 400. Everything one request renders (subjects, bodies, recipients) may total at most 1,000,000 bytes (400 invalid_input, never truncated). Content: template_id and/or subject + body_text (or body_html, sanitized); the request's fields win over the template's, and merge fields ({{creator_first_name}}, {{display_name}}, {{brand_name}}, {{sender_name}}, …) are filled per recipient. Mailbox: email_account_id, or the member's first mailbox they can send from — another workspace's or one they cannot see is 404, one they may only read is 403 mailbox_permission_required, one that cannot send right now is 409 conflict. follow_up { after_days: 2-14 } schedules an auto follow-up for roster recipients where the plan includes it (403 feature_not_available otherwise). An `external_send`-class action: it sends at once and answers 200 { status: "sent", data: { sent, failed, already_sent, recipients[] … } }, counting each message against the credential's daily recipient cap (default 50, up to 500; 429 daily_send_cap_reached past it, Retry-After to 00:00 UTC). A database error before the first message leaves is 503 service_unavailable (nothing sent, the cap refunded; retry with the same key). Retrying with the same Idempotency-Key never sends twice: within 24 hours it replays the stored answer, and later every message already sent under that key (whatever happened to it since: delivered, opened, replied, bounced) is reported already_sent instead of being sent again. A new key is a new send. Creator names in the result are untrusted text. Requires outreach:write and email:send, an Idempotency-Key, and an admin or manager member. Rate weight 5.

Scopes
outreach:write + email:send
Members
admin, manager
Runs
Directly; external_send class
Idempotency-Key
required
Rate weight
5
Untrusted fields
data.recipients[].to_name data.errors[]

Input

Idempotency-Key header, requiredstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
creator_ids bodyarray of string (uuid) — Roster creator ids in this workspace (at most 100 recipients in all).
recipient_emails bodyarray of string — Literal addresses (at most 100 recipients in all). An address that belongs to a roster creator is sent as that creator; any other valid address is sent as typed.
email_account_id bodystring (uuid) — The mailbox to send from. Default: the member's first mailbox they can send from.
template_id bodystring (uuid) — A template to start from: its subject and body fill whatever you leave out.
subject bodystring — Subject line; merge fields are filled per recipient.
body_text bodystring — Plain-text body (escaped into HTML paragraphs); merge fields are filled per recipient.
body_html bodystring — HTML body instead of body_text, cleaned by the app's email sanitizer.
follow_up bodyobject — Schedule an auto follow-up for roster recipients (plans with auto follow-ups only).

Responses

200Success
202pending_approval — a retry with the same Idempotency-Key found this request's action still open (still running, or queued before in-app approval was removed); poll it
400invalid_input / invalid_json / invalid_id / idempotency_key_required
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden / mailbox_permission_required / feature_not_available
404not_found (unknown, cross-workspace or not visible to the key's member)
409conflict / idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After) / daily_send_cap_reached
500internal_error / idempotent_replay_of_failure
503service_unavailable
GET/api/v1/outreach/historySent outreach emails, newest first: recipient, subject, status (sent, opened, replied, bounced, failed), template and reply snippet.

The outreach history the key's member sees on the app's Sent tab: admins see the workspace's; a manager sees their own sends and their assigned creators'; other members only their own. Filters: creator_id, template_id (another workspace's id is 404), status, q (subject, address or creator name). Paged with page/limit (limit ≤ 100, default 50) and totals. reply_text (the creator's reply as received), creator.display_name and subject (which carries merged creator fields) are text authored outside the agency, wrapped as untrusted content. Requires outreach:read.

Scopes
outreach:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1
Untrusted fields
data[].reply_text data[].creator.display_name data[].subject

Input

page queryinteger — 1-based page, default 1.
limit queryinteger — Page size, default 50.
creator_id querystring (uuid) — Only this roster creator's history.
template_id querystring (uuid) — Only sends of this template.
status query"sent" | "delivered" | "opened" | "replied" | "bounced" | "failed" — Only this status.
q querystring — Search subject, address or creator name.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
GET/api/v1/outreach/history/{log_id}One sent outreach email: recipient, subject, the HTML that was sent, status, reply snippet and send error.

One outreach history entry the key's member can see (the Sent tab's visibility, as list_outreach_history). An entry they cannot see, or another workspace's, is 404. message_text is the HTML that was sent; reply_text is the creator's reply — they, subject and creator.display_name carry text authored outside the agency (merged creator fields, the reply) and are wrapped as untrusted content. Requires outreach:read.

Scopes
outreach:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1
Untrusted fields
data.reply_text data.message_text data.creator.display_name data.subject

Input

log_id path, requiredstring (uuid) — Outreach history entry id.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
GET/api/v1/outreach/statsOutreach email totals and rates (delivered, opened, replied, bounced), by template and by day.

The workspace's outreach email statistics, as the app's Analytics tab shows them to every member: total, delivered, opened, replied, bounced and their rates (percent), by_template (template_id, template_name, sent, opened, replied, bounced) and daily_sends (date, count). Requires outreach:read.

Scopes
outreach:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error