Skip to main content
A campaign is the core unit of work in Leadterra. It bundles together a multi-step email sequence, a set of enrolled leads, and your workspace’s delivery settings into one object you can create, start, pause, and inspect through the API. Because campaigns are fully programmable, your AI agents and GTM workflows can spin them up, monitor their performance, and react to results without any manual intervention.

​
Campaign lifecycle

Every campaign moves through three states. Understanding the transitions helps you build reliable automation around campaign control.
  • Draft — The campaign has been created with POST /v1/campaigns but has not yet started sending. You can modify sequence steps and enroll leads while a campaign is in draft.
  • Running — The campaign is actively sending messages to enrolled leads according to the sequence schedule. Trigger this state with POST /v1/campaigns/:id/start.
  • Paused — Sending is suspended. No new messages go out, but the campaign retains all its data and can be restarted. Trigger this state with POST /v1/campaigns/:id/pause.
You can enroll additional leads into a running campaign at any time using the bulk upsert endpoint. Newly enrolled leads start at step one of the sequence regardless of where existing leads are in the flow.

​
Creating a campaign

Use POST /v1/campaigns to create a draft campaign. You can define all sequence steps up front or add them before you start the campaign. 
curl -X POST https://app.leadterra.co/v1/campaigns \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VP Sales — AI Workflow Q1",
    "sequenceSteps": [
      {
        "stepNumber": 1,
        "delayDays": 0,
        "subject": "Quick question, {{firstName}}",
        "bodyHtml": "<p>Hi {{firstName}},</p><p>I noticed {{company}} is expanding its sales team — we help companies like yours book more qualified meetings. Worth a 15-minute call this week?</p>"
      },
      {
        "stepNumber": 2,
        "delayDays": 3,
        "subject": "Following up, {{firstName}}",
        "bodyHtml": "<p>Hi {{firstName}},</p><p>Just wanted to bump this in case it got buried. Happy to share a quick overview if that helps.</p>"
      }
    ]
  }'
Sample response 
{
  "data": {
    "id": "camp_01hx4mrqpbcn7wh2gfk9yz6e3s",
    "name": "VP Sales — AI Workflow Q1",
    "status": "draft",
    "sequenceSteps": 2,
    "createdAt": "2025-01-15T09:00:00Z"
  }
}
The campaign is created in draft state. You can now enroll leads with POST /v1/campaigns/:id/leads/bulk and then call POST /v1/campaigns/:id/start to begin sending.

​
Sequence steps

A sequence is an ordered list of steps, where each step is one email in the outbound thread. Every step has a subject and a bodyHtml. When you create a campaign you define all steps up front, and Leadterra spaces them according to the delay you configure on each step. Example sequence step object 
{
  "stepNumber": 1,
  "delayDays": 0,
  "subject": "Quick question, {{firstName}}",
  "bodyHtml": "<p>Hi {{firstName}},</p><p>I noticed that {{company}} is expanding its engineering team — we help companies like yours source qualified candidates 3x faster. Worth a 15-minute call this week?</p><p>Best,<br>James</p>"
}
Personalization tokens let you tailor every message to the individual lead. The following tokens are available out of the box:
TokenResolved from
{{firstName}}Lead’s firstName field
{{company}}Lead’s company field
{{jobTitle}}Lead’s jobTitle field
You can also use any custom field you include when uploading leads — see Leads for details.
If a lead is missing the field a token references, Leadterra replaces the token with an empty string by default. Always verify your lead data is complete before starting a campaign to avoid awkward gaps like “Hi ,” in your subject lines.

​
Campaign stats

Once a campaign is running, use GET /v1/campaigns/:id/stats to pull performance metrics: 
curl https://app.leadterra.co/v1/campaigns/camp_01hx4mrqpbcn7wh2gfk9yz6e3s/stats \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
Sample response 
{
  "data": {
    "campaignId": "camp_01hx4mrqpbcn7wh2gfk9yz6e3s",
    "status": "running",
    "enrolledLeads": 412,
    "metrics": {
      "delivered": 389,
      "queued": 23,
      "bounced": 8,
      "replied": 47,
      "replyRate": 0.121
    },
    "updatedAt": "2025-01-15T14:22:00Z"
  }
}
The four core metrics tell you the full delivery story:
  • delivered — Messages successfully accepted by the recipient’s mail server.
  • queued — Messages waiting to send, either because of daily capacity limits or step delays.
  • bounced — Messages permanently rejected by the recipient’s mail server.
  • replied — Leads who sent at least one reply to any step in the sequence.
You can also subscribe to the campaign.started, message.sent, and message.bounced webhook events to receive these signals in real time rather than polling the stats endpoint.