AI CMO - Truthlocks Documentation

The AI CMO is an autopilot for enterprise outbound. It handles the full campaign lifecycle — lead discovery, AI scoring, personalized email generation, reply classification, follow-up sequencing, and CRM sync — so you can launch targeted outreach without manual effort. You manage campaigns from the Growth section of the console or through the platform API. Once a campaign is activated, the AI CMO orchestrator runs continuously, processing leads and sending emails within the safety limits you configure.

How it works

The AI CMO processes each active campaign through a repeating loop:

Discover leads. When a campaign has fewer than ten pending leads, the orchestrator automatically discovers new prospects matching your ICP through integrated enrichment providers.
Score leads. Each lead receives an AI-generated qualification score (0–100) with a fit level of high, medium, or low.
Generate emails. Personalized outbound emails are composed by the AI writing model based on the campaign strategy, lead profile, and product knowledge.
Send within safety limits. Every send passes through a seven-layer safety check before delivery. Daily caps, per-minute caps, bounce thresholds, and complaint thresholds are enforced automatically. Emails are also held until the lead’s local business hours (9 am–6 pm, weekdays).
Classify replies. Inbound replies are classified by sentiment — positive, negative, neutral, out-of-office, auto-reply, request for more information, or not interested.
Sync hot leads. Leads that reply positively or request more information are automatically pushed to your CRM with full context, including sentiment score and reply text.
Learn and adjust. After each campaign completes, the system synthesizes what worked — effective personas, messaging angles, subject lines — and applies those learnings to future campaigns. Active campaigns also receive mid-flight strategy adjustments based on bounce and reply rates.

AI model tiers

The AI CMO routes tasks to three model tiers based on complexity:

Tier	Used for
Reasoning	Campaign planning, strategy adjustment, learning synthesis
Fast	Lead scoring, follow-up decisions, reply classification, send-time optimization
Write	Email generation, A/B subject line variants

You can view which models are in use from the Settings page in the Growth section or via the settings API endpoint.

Getting started

Open the Growth section

Navigate to Growth in the console. The dashboard shows an overview of active campaigns, emails sent today, average bounce rate, and total replies.

Choose a campaign approach

You can start outreach in two ways:

Use a template. Ten pre-built campaign templates target specific industry verticals with complete AI strategies. See campaign templates for the full list.
Create from scratch. Define your own ICP, messaging strategy, and safety limits via the API.

Import or discover leads

Add leads to your campaign manually, via bulk import, or let the orchestrator discover them automatically when the campaign is active.To import leads via the API:

curl -X POST https://api.truthlocks.com/v1/platform/growth/leads/import \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "email": "jane.doe@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "company": "Acme Corp",
        "title": "VP Compliance",
        "country": "US",
        "timezone": "America/New_York"
      }
    ]
  }'

The country and timezone fields are optional. If provided, they enable timezone-aware outreach so emails arrive during the lead’s local business hours.

Activate the campaign

Activate from the console or via the API:

curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/activate \
  -H "X-API-Key: tl_live_your_api_key"

The orchestrator begins processing leads and generating emails immediately.

Monitor from the dashboard

Track campaign performance in real time from the Growth dashboard. Click into any campaign to open the detail view with six tabs:

Overview — campaign strategy, status, and configuration
Leads — all leads associated with the campaign, their status, and follow-up count
Emails — every email generated by the AI, with delivery status and content hash
Pending Approval — emails awaiting your review (when approval mode is enabled)
Analytics — sent, bounced, and replied counts at a glance
Learnings — AI-synthesized insights on effective personas, industries, and messaging

You can also query all of these through the campaign detail endpoints.

Growth dashboard

The Growth section of the console opens to a dashboard that gives you an at-a-glance view of your outbound program. The dashboard displays four key metrics:

Metric	Description
Active campaigns	Number of campaigns currently in the `active` state
Emails today	Total emails sent across all campaigns in the current day
Avg bounce rate	Weighted average bounce rate across active campaigns
Total replies	Sum of all replies received across active campaigns

Below the metrics, the dashboard shows two panels:

Recent campaigns — a list of your most recent campaigns with their status, emails sent count, and reply rate. Click any campaign to open its detail view.
Recent activity — an audit log of the last ten events across all campaigns, showing what happened and when. Use this to spot issues like bounces or auto-pauses without clicking into individual campaigns.

Dashboard API

Retrieve the same data programmatically:

curl -X GET https://api.truthlocks.com/v1/platform/growth/dashboard \
  -H "X-API-Key: tl_live_your_api_key"

The response includes:

{
  "stats": {
    "active_campaigns": 3,
    "emails_today": 42,
    "avg_bounce_rate": 2.1,
    "total_replies": 17
  },
  "recent_campaigns": [
    {
      "id": "campaign_abc123",
      "name": "Q2 SaaS Engineering Outreach",
      "status": "active",
      "emails_sent": 128,
      "reply_rate": 4.7
    }
  ],
  "recent_activity": [
    {
      "message": "Campaign 'Q2 SaaS Engineering Outreach' sent 12 emails",
      "timestamp": "2026-03-27T14:32:00Z"
    }
  ]
}

The dashboard refreshes in real time. The bounce rate card turns red when the average exceeds 3%, signaling that one or more campaigns may need attention.

Knowledge base

The knowledge base stores product information that the AI CMO uses to personalize outreach emails. Knowledge entries are injected into every AI prompt, giving the writing model context about your product, ideal customers, and competitive positioning. Entries carry forward across campaigns — when you add or update a knowledge entry, every future campaign benefits from it automatically.

Knowledge categories

Each entry belongs to one of these categories:

Category	Description
`feature`	Product features and capabilities
`use_case`	Specific workflows or problems your product solves
`icp`	Ideal customer profile descriptions
`persona`	Target buyer personas
`pain_point`	Customer pain points your product addresses
`differentiator`	What sets your product apart from alternatives
`objection_handler`	Responses to common prospect objections
`pricing`	Pricing information and positioning
`industry`	Industry-specific context and terminology

Managing entries in the console

Open Growth > Knowledge Base in the console. From this page you can:

Add entries — click New Entry, choose a category, and provide a title, content, and priority (0–100).
Edit entries — click any entry to update its title, content, category, or priority.
Toggle active/inactive — each entry has an active switch that controls whether it is injected into AI prompts. Deactivate an entry to temporarily exclude it from AI-generated emails without deleting it.
Delete entries — permanently remove entries you no longer want the AI to reference.
Filter by category — use the category tabs to narrow the list.

Higher-priority entries (70+) are weighted more heavily in AI prompts. Use priority to control which product angles the AI emphasizes most.

Use the active toggle to A/B test messaging angles. Deactivate a differentiator or objection handler, run a campaign, and compare reply rates against a campaign where the entry was active.

Managing entries via the API

List all entries

curl -X GET https://api.truthlocks.com/v1/platform/growth/knowledge \
  -H "X-API-Key: tl_live_your_api_key"

Returns all active knowledge entries ordered by priority (highest first).

Create an entry

curl -X POST https://api.truthlocks.com/v1/platform/growth/knowledge \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "differentiator",
    "title": "Cryptographic proof vs. watermarking",
    "content": "Unlike digital watermarks that can be stripped, Truthlocks uses cryptographic attestations anchored to immutable ledgers. This provides tamper-evident proof that survives format conversion, re-encoding, and redistribution.",
    "priority": 80
  }'

Field	Type	Required	Description
`category`	string	Yes	One of the knowledge categories
`title`	string	Yes	Short descriptive title
`content`	string	Yes	Full text the AI uses for context
`priority`	integer	No	0–100, defaults to 50. Higher values are weighted more in AI prompts
`active`	boolean	No	Defaults to `true`. Set to `false` to exclude this entry from AI prompts without deleting it

Update an entry

curl -X PATCH https://api.truthlocks.com/v1/platform/growth/knowledge/{id} \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated content with new competitive positioning.",
    "priority": 90
  }'

You can update any combination of title, content, category, priority, and active in a single request. Toggle active to false to temporarily exclude an entry from AI prompts:

curl -X PATCH https://api.truthlocks.com/v1/platform/growth/knowledge/{id} \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"active": false}'

Delete an entry

curl -X DELETE https://api.truthlocks.com/v1/platform/growth/knowledge/{id} \
  -H "X-API-Key: tl_live_your_api_key"

Deleted entries are deactivated and no longer included in AI prompts.

Campaign learnings

After a campaign completes, the AI synthesizes what worked into campaign learnings. These learnings capture effective personas, industries, messaging angles, subject lines, and reply rates. You can view learnings in the Learnings tab of any campaign detail view, or retrieve them via the API. To list recent learnings across all campaigns:

curl -X GET https://api.truthlocks.com/v1/platform/growth/knowledge/learnings \
  -H "X-API-Key: tl_live_your_api_key"

Each learning includes:

Field	Type	Description
`id`	string	Unique learning identifier
`campaign_id`	string	Campaign that generated the learning
`summary`	string	AI-generated summary of what worked
`effective_personas`	array	Buyer personas that responded well
`effective_industries`	array	Industry verticals with the highest engagement
`ineffective_angles`	array	Messaging approaches that underperformed
`best_subject_lines`	array	Subject lines with the highest open or reply rates
`reply_rate_pct`	number	Overall reply rate for the campaign
`bounce_rate_pct`	number	Overall bounce rate for the campaign
`emails_analyzed`	integer	Number of emails included in the analysis

Review learnings regularly to refine your knowledge base. If the AI identifies a persona or industry that performs well, consider adding a dedicated knowledge entry to reinforce that angle in future campaigns.

Campaign lifecycle

Campaigns move through these states:

Transition	Trigger	Effect
`draft` → `active`	Activate	Orchestrator begins processing and sending
`active` → `paused`	Pause or auto-pause	Sending stops; campaign can be resumed
`paused` → `active`	Resume	Sending resumes from where it left off
`active` → `paused`	Kill switch	Emergency stop — sets the kill switch and pauses
`active` → `completed`	Automatic	All leads have been processed and at least one email has been sent

A campaign only auto-completes when all leads have been exhausted and at least one email has been sent. This prevents newly activated campaigns from completing instantly before lead discovery has had a chance to run. If a campaign has zero sends, the orchestrator keeps it active until leads are discovered and processed. Campaigns auto-pause when the bounce rate or complaint rate exceeds the configured threshold.

Timezone-aware outreach

The AI CMO only sends emails during local business hours — 9 am to 6 pm, Monday through Friday — in each lead’s timezone. Emails are never sent on weekends. If a lead’s send window is closed, the email is automatically deferred to 9 am on the next weekday in the lead’s local time. The deferred send is stored on the lead record and picked up by the orchestrator when the window opens — no manual intervention is needed. Timezone-aware sending is always active for every campaign. There is nothing to enable or configure.

How timezones are resolved

Timezones are resolved in this order:

Explicit timezone — if you set a timezone value (IANA format, e.g. America/New_York) when importing the lead, that value is used.
Country lookup — if no timezone is set but a country is present (ISO 3166-1 alpha-2, e.g. US, GB), the timezone is inferred automatically from the supported country list.
Auto-discovered leads — leads found through enrichment providers have their country and timezone populated automatically during discovery.
Fallback — if neither timezone nor country is available, the system falls back to UTC.

For countries that span multiple timezones, the most common business timezone is used. For example, US maps to America/New_York (Eastern Time) and AU maps to Australia/Sydney.

Supported countries

52 countries are mapped to IANA timezones across five regions.

Americas
Europe
Middle East & Africa
Asia-Pacific

Country code	Timezone
US	America/New_York
CA	America/Toronto
MX	America/Mexico_City
BR	America/Sao_Paulo
AR	America/Argentina/Buenos_Aires
CL	America/Santiago
CO	America/Bogota
PE	America/Lima
VE	America/Caracas

Country code	Timezone
GB	Europe/London
IE	Europe/Dublin
FR	Europe/Paris
DE	Europe/Berlin
NL	Europe/Amsterdam
BE	Europe/Brussels
CH	Europe/Zurich
AT	Europe/Vienna
ES	Europe/Madrid
PT	Europe/Lisbon
IT	Europe/Rome
SE	Europe/Stockholm
NO	Europe/Oslo
DK	Europe/Copenhagen
FI	Europe/Helsinki
PL	Europe/Warsaw
CZ	Europe/Prague
RO	Europe/Bucharest
HU	Europe/Budapest
GR	Europe/Athens
TR	Europe/Istanbul
RU	Europe/Moscow
UA	Europe/Kiev
LU	Europe/Luxembourg
SK	Europe/Bratislava
HR	Europe/Zagreb

Country code	Timezone
AE	Asia/Dubai
SA	Asia/Riyadh
IL	Asia/Jerusalem
EG	Africa/Cairo
ZA	Africa/Johannesburg
NG	Africa/Lagos
KE	Africa/Nairobi
QA	Asia/Qatar
KW	Asia/Kuwait
BH	Asia/Bahrain

Country code	Timezone
IN	Asia/Kolkata
CN	Asia/Shanghai
JP	Asia/Tokyo
KR	Asia/Seoul
SG	Asia/Singapore
HK	Asia/Hong_Kong
TW	Asia/Taipei
AU	Australia/Sydney
NZ	Pacific/Auckland
MY	Asia/Kuala_Lumpur
TH	Asia/Bangkok
ID	Asia/Jakarta
PH	Asia/Manila
VN	Asia/Ho_Chi_Minh
PK	Asia/Karachi
BD	Asia/Dhaka
LK	Asia/Colombo

You can override the inferred timezone for any lead by setting the timezone field explicitly during import. Use this when a lead is based in a different timezone than their country’s default — for example, a US-based lead working from America/Los_Angeles.

How deferral works

When the orchestrator processes a lead and the lead’s local time falls outside the 9 am–6 pm weekday window, the following happens:

The email is not generated or sent.
The lead’s next follow-up time is set to 9 am on the next weekday in their local timezone.
The orchestrator skips the lead until that time arrives.

This means a lead in Asia/Tokyo processed at 11 pm JST on a Friday will not receive their email until 9 am JST on the following Monday. Follow-up emails use a 48-hour interval by default. If the 48-hour mark falls outside business hours, the follow-up is deferred to the next business-hours window automatically.

Safety controls

Every email passes through a seven-layer safety check before sending:

Global kill switch — operator-level emergency stop across all campaigns.
Campaign kill switch — stops a single campaign immediately.
Campaign status — only active campaigns can send.
Daily send cap — maximum emails per day per campaign (default: 50).
Per-minute cap — sliding-window rate limit per campaign (default: 5).
Bounce rate threshold — auto-pauses the campaign if exceeded (default: 5%).
Complaint rate threshold — auto-pauses the campaign if exceeded (default: 0.1%).

When a campaign is auto-paused due to bounce or complaint thresholds, you must investigate the cause before resuming. This protects your sender reputation.

Managing campaigns via the API

Create a campaign

curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 SaaS Engineering Outreach",
    "description": "Target engineering leaders at B2B SaaS companies",
    "ai_strategy": {
      "icp_description": "CTOs and VP Engineering at B2B SaaS companies with 50-500 employees building document workflows",
      "outbound_strategy": "Lead with document integrity pain points, position Truthlocks as infrastructure",
      "key_value_props": [
        "Cryptographic proof of document authenticity",
        "Drop-in SDK integration in under an hour",
        "Compliance-ready audit trail for SOC 2 and ISO 27001"
      ],
      "tone_guidelines": "Technical and direct. Avoid marketing jargon. Speak as an engineer to an engineer.",
      "followup_cadence": "Day 1: Intro email. Day 4: Technical deep-dive. Day 10: Case study. Day 18: Final follow-up.",
      "subject_line_formulas": [
        "Document integrity for {company}",
        "How {company} can prove file authenticity",
        "Quick question about document workflows at {company}"
      ]
    },
    "daily_cap": 40,
    "per_minute_cap": 5,
    "max_followups": 3,
    "simulation_mode": false,
    "approval_required": false
  }'

The request accepts these fields:

Field	Type	Required	Description
`name`	string	yes	Campaign name
`description`	string	no	Brief description of the campaign’s purpose
`audience_description`	string	no	Plain-text description of the target audience for AI lead discovery
`ai_strategy`	object	no	AI strategy configuration (see below)
`daily_cap`	integer	no	Maximum emails per day (default: 50)
`per_minute_cap`	integer	no	Sliding-window rate limit per minute (default: 5)
`max_followups`	integer	no	Maximum follow-up emails per lead (default: 3)
`simulation_mode`	boolean	no	Run the campaign without sending real emails (default: `false`)
`approval_required`	boolean	no	Hold every email for manual review before sending (default: `false`)

The response returns the full campaign object:

Field	Type	Description
`id`	string	Unique campaign identifier
`name`	string	Campaign name
`description`	string	Campaign description
`status`	string	Current state — `draft`, `active`, `paused`, `completed`, or `failed`
`simulation_mode`	boolean	Whether the campaign runs in simulation mode
`approval_required`	boolean	Whether emails require manual approval before sending
`ai_strategy`	object	The AI strategy including ICP, messaging, and cadence
`daily_cap`	integer	Daily send limit
`per_minute_cap`	integer	Per-minute rate limit
`max_followups`	integer	Maximum follow-ups per lead
`bounce_threshold_pct`	number	Bounce rate auto-pause threshold (percentage)
`complaint_threshold_pct`	number	Complaint rate auto-pause threshold (percentage)
`kill_switch`	boolean	Whether the emergency kill switch is active
`activated_at`	string or null	ISO 8601 timestamp when the campaign was activated
`completed_at`	string or null	ISO 8601 timestamp when the campaign completed
`created_at`	string	ISO 8601 timestamp when the campaign was created
`updated_at`	string	ISO 8601 timestamp of the last update

Pause, resume, or kill a campaign

# Pause
curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/pause \
  -H "X-API-Key: tl_live_your_api_key"

# Resume
curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/resume \
  -H "X-API-Key: tl_live_your_api_key"

# Emergency kill switch
curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/kill \
  -H "X-API-Key: tl_live_your_api_key"

Simulation mode

Simulation mode lets you preview the full orchestrator pipeline — lead discovery, scoring, and email generation — without delivering any emails. When simulation_mode is true on a campaign, every email the AI generates is recorded with a status of simulated instead of being sent through SES. Use simulation mode to validate your ICP, review generated email content, and confirm safety limits before switching to live delivery. Set simulation mode when creating a campaign:

curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Campaign - Simulation",
    "simulation_mode": true,
    "ai_strategy": { ... }
  }'

Simulation mode campaigns display a violet SIM badge in the campaign list and a Simulation Mode badge on the detail page. Individual emails show a Simulated indicator so you can distinguish them from real sends.

Filtering emails by simulation status

In the console, the Emails tab provides a tri-state filter to view simulated emails only, real emails only, or both. Via the API, the simulation boolean on each email object indicates whether the email was simulated.

Global simulation default

You can set simulation_default to true in the Growth settings so that every new campaign starts in simulation mode by default. Individual campaigns can still override this at creation time by explicitly setting simulation_mode to false.

Approval mode

When approval_required is set to true, every AI-generated email is held with a status of pending_approval instead of being sent automatically. You review and approve each email individually from the Pending Approval tab in the console or via the approve endpoint. Only after approval does the email move to queued and enter the normal send pipeline. This gives you full control over outbound messaging before any email leaves the system. Approval mode is useful when:

You are launching a campaign targeting a sensitive audience and want to review every message.
Compliance requires human review of AI-generated outbound content.
You want to spot-check email quality before allowing autonomous delivery.

Set approval mode when creating a campaign:

curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Compliance Outreach - Manual Review",
    "approval_required": true,
    "ai_strategy": { ... }
  }'

Approval mode campaigns display an amber Approval Required badge on the campaign detail page.

Approval workflow

The orchestrator generates an email and sets its status to pending_approval.
The email appears in the Pending Approval tab in the console, or in the response from GET /campaigns/{id}/pending.
You review the subject, recipient, and email body.
Approve the email via the console or by calling POST /campaigns/{id}/emails/{emailId}/approve.
The email status changes to queued and enters the standard send pipeline — safety controls, daily caps, and timezone-aware delivery still apply.

Combine simulation mode and approval mode during onboarding. This lets you review AI-generated emails in a safe environment before enabling real delivery — set simulation_mode: true and approval_required: true together.

Campaign detail endpoints

Once a campaign is created, you can query its leads, emails, pending approvals, stats, and learnings through campaign-scoped endpoints. These are the same endpoints that power the campaign detail tabs in the console. All endpoints below are scoped to a single campaign by ID.

Endpoint	Method	Description
`/campaigns/{id}/leads`	`GET`	List leads with pagination
`/campaigns/{id}/emails`	`GET`	List all generated emails
`/campaigns/{id}/pending`	`GET`	List emails awaiting approval
`/campaigns/{id}/stats`	`GET`	Get delivery and engagement metrics
`/campaigns/{id}/learnings`	`GET`	Get AI-synthesized campaign learnings
`/campaigns/{id}/emails/{emailId}/approve`	`POST`	Approve a pending email
`/campaigns/{id}/leads`	`POST`	Add a lead to the campaign

List campaign leads

Retrieve leads associated with a specific campaign, with pagination support:

curl -X GET "https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/leads?limit=20&offset=0" \
  -H "X-API-Key: tl_live_your_api_key"

Each lead in the response includes:

Field	Type	Description
`id`	string	Unique lead identifier
`email`	string	Lead’s email address
`status`	string	Current status (e.g. `pending`, `sent`, `bounced`, `replied`)
`followup_count`	integer	Number of follow-up emails sent to this lead
`last_sent_at`	string or null	ISO 8601 timestamp of the most recent email sent, or `null` if none

List campaign emails

Retrieve all emails generated for a campaign:

curl -X GET https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/emails \
  -H "X-API-Key: tl_live_your_api_key"

Each email in the response includes:

Field	Type	Description
`id`	string	Unique email identifier
`campaign_id`	string	Parent campaign identifier
`lead_id`	string	Associated lead identifier
`sequence_number`	integer	Position in the follow-up sequence (1 = initial, 2+ = follow-ups)
`subject`	string	Email subject line
`html_body`	string	Full HTML body of the generated email
`status`	string	Delivery status — see email statuses below
`simulation`	boolean	`true` if this email was simulated rather than sent via SES
`content_hash`	string	SHA-256 hash of the email body for integrity verification
`ai_model`	string	Model ID used to generate the email
`ai_prompt_hash`	string	Hash of the AI prompt used for generation
`ses_message_id`	string or null	SES message ID for delivered emails, or `null` for simulated/pending emails
`sent_at`	string or null	ISO 8601 timestamp when the email was sent, or `null` if not yet delivered
`created_at`	string	ISO 8601 timestamp when the email record was created

Email statuses

Status	Description
`pending_approval`	Email is waiting for manual review (when approval mode is enabled)
`queued`	Email is approved and waiting to be sent
`sent`	Email was sent via SES
`delivered`	SES confirmed delivery to the recipient’s mail server
`bounced`	Email bounced — recipient address is invalid or mailbox is full
`complained`	Recipient marked the email as spam
`simulated`	Email was generated but not sent because simulation mode is active
`failed`	Terminal delivery failure

List pending approvals

Retrieve emails awaiting manual approval before sending. This endpoint only returns results when the campaign has approval_required set to true.

curl -X GET https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/pending \
  -H "X-API-Key: tl_live_your_api_key"

Each pending email in the response includes:

Field	Type	Description
`id`	string	Unique email identifier — pass this to the approve endpoint
`subject`	string	Email subject line
`to`	string	Recipient email address
`html_body`	string	Full HTML body so you can review the content before approving
`status`	string	Always `pending_approval` for this endpoint
`created_at`	string	ISO 8601 timestamp when the email was generated

Get campaign stats

Retrieve delivery and engagement metrics for a campaign:

curl -X GET https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/stats \
  -H "X-API-Key: tl_live_your_api_key"

The response includes:

Field	Type	Description
`total_sent`	integer	Total emails successfully sent
`total_bounced`	integer	Total emails that bounced
`total_complained`	integer	Total emails marked as spam by recipients
`total_replied`	integer	Total replies received
`bounce_rate_pct`	number	Bounce rate as a percentage of total sent
`reply_rate_pct`	number	Reply rate as a percentage of total sent

Get campaign learnings

After a campaign completes, the AI synthesizes what worked. Retrieve those learnings:

curl -X GET https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/learnings \
  -H "X-API-Key: tl_live_your_api_key"

Each learning in the response includes:

Field	Type	Description
`id`	string	Unique learning identifier
`campaign_id`	string	Campaign this learning was synthesized from
`summary`	string	AI-generated summary of what worked
`effective_personas`	array of strings	Buyer personas that responded well
`effective_industries`	array of strings	Industry verticals with the highest engagement
`effective_angles`	array of strings	Messaging angles that drove replies
`ineffective_angles`	array of strings	Angles that performed poorly
`best_subject_lines`	array of strings	Top-performing subject lines from the campaign
`reply_rate_pct`	number or null	Overall reply rate for the analyzed emails
`bounce_rate_pct`	number or null	Overall bounce rate for the analyzed emails
`emails_analyzed`	integer	Number of emails included in the learning synthesis
`ai_model`	string	Model used to synthesize the learnings
`created_at`	string	ISO 8601 timestamp when the learning was generated

The orchestrator applies these learnings automatically to future campaigns targeting similar audiences.

Approve a pending email

If your campaign uses approval mode, approve a specific email to queue it for sending:

curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/emails/{emailId}/approve \
  -H "X-API-Key: tl_live_your_api_key"

Once approved, the email enters the normal send pipeline and is subject to safety controls — daily caps, per-minute limits, and timezone-aware delivery still apply.

Add a lead to a campaign

Attach an existing lead to a campaign:

curl -X POST https://api.truthlocks.com/v1/platform/growth/campaigns/{id}/leads \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"lead_id": "lead_abc123"}'

Lead management

The Growth > Leads page in the console is your central hub for managing outbound leads across all campaigns.

Managing leads in the console

From the leads page you can:

Add a lead — click Add Lead and fill in email, name, company, title, and industry.
Import leads from CSV — click Import, upload a CSV file with columns email, first_name, last_name, company, title, and industry, and optionally assign all imported leads to a campaign.
Score a lead with AI — click Score next to any lead to trigger AI-powered qualification scoring. The AI returns a numeric score (0–100) that updates in place.
Add a lead to a campaign — click Add to Campaign next to any lead and select the target campaign from the dropdown.

Lead statuses are color-coded in the table: new, qualified, contacted, replied, converted, unsubscribed, and bounced.

Import leads via the API

curl -X POST https://api.truthlocks.com/v1/platform/growth/leads/import \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {
        "email": "cto@example.com",
        "first_name": "Alex",
        "last_name": "Chen",
        "company": "DataFlow Inc",
        "title": "CTO",
        "country": "GB"
      }
    ]
  }'

Score a lead

Trigger AI scoring for a specific lead with optional campaign context:

curl -X POST https://api.truthlocks.com/v1/platform/growth/leads/{id}/score \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_context": "Enterprise compliance officers at financial services firms"
  }'

The response includes a score (0–100), a fit level (high, medium, or low), and the AI’s reasoning.

Email management

The Growth > Emails page in the console shows a log of all AI-generated emails across every campaign. Use it to monitor delivery status, review email content, and spot problems.

Filtering the email log

Three filters narrow the log:

Filter	Options
Campaign	Select a specific campaign or view all
Status	`pending_approval`, `queued`, `sent`, `delivered`, `bounced`, `complained`, `simulated`, `failed`
Simulation	All emails, simulated only, or real only

Viewing email details

Click any email in the log to open a detail drawer showing:

Subject and status — the email subject line with a status badge.
Content hash — the SHA-256 hash of the email body, useful for integrity verification.
AI prompt hash — the hash of the prompt used to generate the email.
SES message ID — the Amazon SES tracking ID for delivered emails.
Event timeline — a chronological list of delivery events (send, delivery, bounce) with timestamps.
Body preview — the rendered HTML email body so you can review exactly what the recipient saw.

Cross-campaign approval queue

The Growth > Emails > Pending Approval page shows all emails awaiting manual approval across every campaign that has approval mode enabled. This gives you a single queue to review and approve outbound emails without opening each campaign individually. Each entry shows the campaign name, recipient, subject line, and generation timestamp. Click Approve to send the email into the delivery pipeline.

Reply classification

The AI CMO classifies every inbound reply with one of these sentiment labels:

Sentiment	Description
`positive`	Interested in learning more or scheduling a meeting
`negative`	Clearly not interested or hostile
`neutral`	Acknowledgment without clear intent
`out_of_office`	Auto-reply indicating the contact is away
`auto_reply`	Non-human automated response
`request_more_info`	Asking for additional details
`not_interested`	Polite decline

Replies classified as positive or request_more_info are flagged as hot leads and trigger CRM sync and optional webhooks.

CRM integration

Hot leads are automatically pushed to your connected CRM. Currently supported:

HubSpot — contacts are created with the lead source set to “Truthlocks AI CMO”, and a note is attached with the campaign ID, sentiment score, and reply text.

Configure CRM integration from the Growth Settings page or by setting the CRM provider and API key in your platform configuration.

Knowledge base

The knowledge base teaches the AI what to say. Every active entry is injected into the AI prompt when generating outbound emails, so the content you add here directly shapes messaging across all campaigns. Manage entries from the Knowledge page in the Growth section of the console, or through the API.

Entry structure

Each knowledge entry has four fields:

Field	Type	Description
`category`	string	Classifies the entry — one of `feature`, `use_case`, `icp`, `persona`, `pain_point`, `differentiator`, `objection_handler`, `pricing`, or `industry`
`title`	string	Short label for the entry (required)
`content`	string	The knowledge content injected into AI prompts (required)
`priority`	integer	Weight from 0–100 that controls how prominently the entry is used. High (70–100), medium (40–69), low (0–39)
`active`	boolean	Toggle an entry on or off without deleting it

Entries carry forward across campaigns. When you improve an entry or add a new one, every future email benefits automatically.

When to use each category

Category	Use for
Feature	Product capabilities you want the AI to reference
Use case	Specific workflows or scenarios your product solves
ICP	Descriptions of your ideal customer profiles
Persona	Buyer persona details — role, priorities, pain points
Pain point	Problems your target audience faces that your product addresses
Differentiator	What sets you apart from alternatives
Objection handler	Responses to common objections or concerns
Pricing	Pricing details, tiers, or value framing
Industry	Industry-specific context the AI should know

Create an entry

curl -X POST https://api.truthlocks.com/v1/platform/growth/knowledge \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "differentiator",
    "title": "Offline verification",
    "content": "Truthlocks proof bundles can be verified entirely offline using browser-native cryptography. No API call or internet connection is needed for the first three verification steps. This is unique in the market and critical for air-gapped environments.",
    "priority": 80,
    "active": true
  }'

Update an entry

curl -X PATCH https://api.truthlocks.com/v1/platform/growth/knowledge/{id} \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated content for this entry",
    "priority": 90
  }'

You can also toggle an entry on or off by patching only the active field.

Delete an entry

curl -X DELETE https://api.truthlocks.com/v1/platform/growth/knowledge/{id} \
  -H "X-API-Key: tl_live_your_api_key"

List all entries

curl -X GET https://api.truthlocks.com/v1/platform/growth/knowledge \
  -H "X-API-Key: tl_live_your_api_key"

The response returns an array of entries. Filter by category in the console using the tab bar.

Campaign intelligence

The Campaign Intelligence section on the knowledge page shows what the AI has learned from completed campaigns. Each row includes:

Field	Description
Campaign	The campaign the learning was synthesized from
Summary	AI-generated summary of what worked
Reply rate	Percentage of emails that received replies
Bounce rate	Percentage of emails that bounced
Emails analyzed	Number of emails included in the analysis
Top personas	Buyer personas that responded well
Top industries	Industry verticals with the highest engagement

Retrieve learnings via the API:

curl -X GET https://api.truthlocks.com/v1/platform/growth/knowledge/learnings \
  -H "X-API-Key: tl_live_your_api_key"

The orchestrator applies these learnings automatically to future campaigns targeting similar audiences.

Start with a few high-priority entries in the differentiator and pain_point categories. These have the biggest impact on email quality because they give the AI concrete talking points rather than generic messaging.

Settings

Retrieve settings

Retrieve your AI CMO configuration:

curl -X GET https://api.truthlocks.com/v1/platform/growth/settings \
  -H "X-API-Key: tl_live_your_api_key"

Key settings fields:

Field	Type	Description
`daily_email_cap`	integer	Platform-wide default daily send cap
`per_minute_cap`	integer	Platform-wide default per-minute cap
`max_follow_ups`	integer	Default maximum follow-up emails per lead
`bounce_rate_pause_threshold`	number	Default bounce rate threshold for auto-pause (percentage)
`complaint_rate_pause_threshold`	number	Default complaint rate threshold for auto-pause (percentage)
`simulation_default`	boolean	When `true`, new campaigns start in simulation mode by default
`global_kill_switch`	boolean	Emergency stop for all campaigns — no emails are sent while active
`ses_status`	string	Current SES health — `healthy`, `degraded`, or `unavailable` (read-only)
`bedrock_model_id`	string	Primary AI model for campaign planning and reasoning (read-only)
`cloudwatch_metrics_url`	string or null	Link to the CloudWatch dashboard for delivery metrics

Update settings

Update one or more settings with a PATCH request:

curl -X PATCH https://api.truthlocks.com/v1/platform/growth/settings \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_email_cap": 100,
    "per_minute_cap": 10,
    "bounce_rate_pause_threshold": 3.0,
    "simulation_default": true
  }'

You can update any combination of writable fields in a single request. Read-only fields like ses_status and bedrock_model_id are ignored if included.

Global kill switch

The global kill switch immediately stops all active campaigns from sending emails. When activated, no emails are sent across any campaign until you deactivate it. From the console: Open Growth > Settings and toggle Global Kill Switch under the Safety section. A confirmation dialog requires you to confirm before activation to prevent accidental use. From the API:

curl -X PATCH https://api.truthlocks.com/v1/platform/growth/settings \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"global_kill_switch": true}'

To deactivate the kill switch and resume sending:

curl -X PATCH https://api.truthlocks.com/v1/platform/growth/settings \
  -H "X-API-Key: tl_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"global_kill_switch": false}'

The global kill switch affects every campaign. Use the campaign-level kill switch at POST /campaigns/{id}/kill if you only need to stop a single campaign.

Campaign templates

Activate pre-built campaigns for ten industry verticals.

Webhooks

Receive real-time notifications for campaign events including hot lead replies.

Authentication

Set up your API key for growth API access.

Error reference

Troubleshoot API errors including retryable vs. terminal failures.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Specification

SDKs

​How it works

​AI model tiers

​Getting started

​Growth dashboard

​Dashboard API

​Knowledge base

​Knowledge categories

​Managing entries in the console

​Managing entries via the API

​List all entries

​Create an entry

​Update an entry

​Delete an entry

​Campaign learnings

​Campaign lifecycle

​Timezone-aware outreach

​How timezones are resolved

​Supported countries

​How deferral works

​Safety controls

​Managing campaigns via the API

​Create a campaign

​Pause, resume, or kill a campaign

​Simulation mode

​Filtering emails by simulation status

​Global simulation default

​Approval mode

​Approval workflow

​Campaign detail endpoints

​List campaign leads

​List campaign emails

​Email statuses

​List pending approvals

​Get campaign stats

​Get campaign learnings

​Approve a pending email

​Add a lead to a campaign

​Lead management

​Managing leads in the console

​Import leads via the API

​Score a lead

​Email management

​Filtering the email log

​Viewing email details

​Cross-campaign approval queue

​Reply classification

​CRM integration

​Knowledge base

​Entry structure

​When to use each category

​Create an entry

​Update an entry

​Delete an entry

​List all entries

​Campaign intelligence

​Settings

​Retrieve settings

​Update settings

​Global kill switch

​Related

Campaign templates

Webhooks

Authentication

Error reference

How it works

AI model tiers

Getting started

Growth dashboard

Dashboard API

Knowledge base

Knowledge categories

Managing entries in the console

Managing entries via the API

List all entries

Create an entry

Update an entry

Delete an entry

Campaign learnings

Campaign lifecycle

Timezone-aware outreach

How timezones are resolved

Supported countries

How deferral works

Safety controls

Managing campaigns via the API

Create a campaign

Pause, resume, or kill a campaign

Simulation mode

Filtering emails by simulation status

Global simulation default

Approval mode

Approval workflow

Campaign detail endpoints

List campaign leads

List campaign emails

Email statuses

List pending approvals

Get campaign stats

Get campaign learnings

Approve a pending email

Add a lead to a campaign

Lead management

Managing leads in the console

Import leads via the API

Score a lead

Email management

Filtering the email log

Viewing email details

Cross-campaign approval queue

Reply classification

CRM integration

Knowledge base

Entry structure

When to use each category

Create an entry

Update an entry

Delete an entry

List all entries

Campaign intelligence

Settings

Retrieve settings

Update settings

Global kill switch

Related