Skip to content
Log in Start for free

AI Email Marketing

Campaigns

Create campaigns, change their content and schedule, add leads, and launch, pause or resume them. A new campaign starts as a draft.

GET/v1/campaignsList campaigns POST/v1/campaignsCreate a campaign GET/v1/campaigns/{id}Get a campaign PATCH/v1/campaigns/{id}Update a campaign POST/v1/campaigns/{id}/launchLaunch a campaign POST/v1/campaigns/{id}/pausePause a campaign POST/v1/campaigns/{id}/resumeResume a campaign GET/v1/campaigns/{id}/leadsList campaign recipients POST/v1/campaigns/{id}/leadsAdd leads to a campaign GET/v1/campaigns/{id}/statsGet campaign stats

List campaigns

GET/api/v1/campaigns

Campaigns, newest first.

Any API key, read-only included.

Parameters

NameTypeDescription
status query string draft, active, paused or completed.
per_page query integer Results per page, up to 100. Default 25.
page query integer Page number.

Errors

  • 401Missing or invalid key
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl https://app.zicreach.com/api/v1/campaigns \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "data": [
        {
            "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
            "name": "Q4 founders",
            "status": "draft",
            "campaign_type": "standard",
            "schedule_type": "immediate",
            "scheduled_at": null,
            "subject_lines": [
                "Quick question, {{first_name|there}}"
            ],
            "email_bodies": [
                "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..."
            ],
            "send_window": {
                "start": "09:00",
                "end": "17:00",
                "days": [
                    "mon",
                    "tue",
                    "wed",
                    "thu",
                    "fri"
                ],
                "timezone": "Europe/London"
            },
            "follow_up": {
                "enabled": true,
                "delay_days": 3,
                "max": 3
            },
            "stop_on_reply": true,
            "stats": {
                "total_leads": 240,
                "sent": 0,
                "opened": 0,
                "clicked": 0,
                "replied": 0,
                "bounced": 0
            },
            "created_at": "2026-09-20T08:00:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "total": 1
    }
}

Create a campaign

POST/api/v1/campaigns

Creates a draft campaign. Everything except name, subject_lines and email_bodies is optional.

Needs a read and write API key.

Body

NameTypeDescription
namerequired string Campaign name.
subject_linesrequired string[] One to five subject lines. More than one is an A/B test.
email_bodiesrequired string[] One to five bodies. Merge fields like {{first_name|there}} work.
timezone string IANA timezone, for example Europe/London.
send_days string[] Any of mon, tue, wed, thu, fri, sat, sun.
send_window_start string HH:MM in the campaign timezone.
send_window_end string HH:MM in the campaign timezone.
delay_between_emails integer Seconds between emails from one mailbox, 30 to 3600.
follow_up_enabled boolean Send follow-ups.
follow_up_delay_days integer Days between follow-ups, 1 to 60.
max_follow_ups integer At most this many follow-ups, 0 to 5.
track_opens boolean Track opens and link clicks.
email_account_ids uuid[] Mailboxes to send from.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X POST https://app.zicreach.com/api/v1/campaigns \
  -H "Authorization: Bearer zk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q4 founders","subject_lines":["Quick question, {{first_name|there}}"],"email_bodies":["Hi {{first_name|there}}, ..."],"timezone":"Europe/London","send_days":["mon","tue","wed","thu","fri"]}'
Response201
{
    "data": {
        "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "name": "Q4 founders",
        "status": "draft",
        "campaign_type": "standard",
        "schedule_type": "immediate",
        "scheduled_at": null,
        "subject_lines": [
            "Quick question, {{first_name|there}}"
        ],
        "email_bodies": [
            "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..."
        ],
        "send_window": {
            "start": "09:00",
            "end": "17:00",
            "days": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri"
            ],
            "timezone": "Europe/London"
        },
        "follow_up": {
            "enabled": true,
            "delay_days": 3,
            "max": 3
        },
        "stop_on_reply": true,
        "stats": {
            "total_leads": 240,
            "sent": 0,
            "opened": 0,
            "clicked": 0,
            "replied": 0,
            "bounced": 0
        },
        "created_at": "2026-09-20T08:00:00Z"
    }
}

Get a campaign

GET/api/v1/campaigns/{id}

One campaign with its settings and running totals.

Any API key, read-only included.

Parameters

NameTypeDescription
idrequired path uuid Campaign id.

Errors

  • 401Missing or invalid key
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl https://app.zicreach.com/api/v1/campaigns/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10 \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "data": {
        "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "name": "Q4 founders",
        "status": "draft",
        "campaign_type": "standard",
        "schedule_type": "immediate",
        "scheduled_at": null,
        "subject_lines": [
            "Quick question, {{first_name|there}}"
        ],
        "email_bodies": [
            "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..."
        ],
        "send_window": {
            "start": "09:00",
            "end": "17:00",
            "days": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri"
            ],
            "timezone": "Europe/London"
        },
        "follow_up": {
            "enabled": true,
            "delay_days": 3,
            "max": 3
        },
        "stop_on_reply": true,
        "stats": {
            "total_leads": 240,
            "sent": 0,
            "opened": 0,
            "clicked": 0,
            "replied": 0,
            "bounced": 0
        },
        "created_at": "2026-09-20T08:00:00Z"
    }
}

Update a campaign

PATCH/api/v1/campaigns/{id}

Send only the fields to change. Accepts the same fields as create.

Needs a read and write API key.

Parameters

NameTypeDescription
idrequired path uuid Campaign id.

Body

NameTypeDescription
name string Campaign name.
subject_lines string[] Replaces the subject lines.
email_bodies string[] Replaces the bodies.
send_window_start string HH:MM.
send_window_end string HH:MM.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X PATCH https://app.zicreach.com/api/v1/campaigns/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10 \
  -H "Authorization: Bearer zk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Q4 founders","subject_lines":["Quick question, {{first_name|there}}"]}'
Response200
{
    "data": {
        "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "name": "Q4 founders",
        "status": "draft",
        "campaign_type": "standard",
        "schedule_type": "immediate",
        "scheduled_at": null,
        "subject_lines": [
            "Quick question, {{first_name|there}}"
        ],
        "email_bodies": [
            "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..."
        ],
        "send_window": {
            "start": "09:00",
            "end": "17:00",
            "days": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri"
            ],
            "timezone": "Europe/London"
        },
        "follow_up": {
            "enabled": true,
            "delay_days": 3,
            "max": 3
        },
        "stop_on_reply": true,
        "stats": {
            "total_leads": 240,
            "sent": 0,
            "opened": 0,
            "clicked": 0,
            "replied": 0,
            "bounced": 0
        },
        "created_at": "2026-09-20T08:00:00Z"
    }
}

Launch a campaign

POST/api/v1/campaigns/{id}/launch

Starts sending. Refused with 422 and a list of blockers when the campaign is not ready (no recipients, no mailbox, no credits).

Needs a read and write API key.

Parameters

NameTypeDescription
idrequired path uuid Campaign id.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X POST https://app.zicreach.com/api/v1/campaigns/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10/launch \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "message": "Campaign launched.",
    "data": {
        "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "name": "Q4 founders",
        "status": "active",
        "campaign_type": "standard",
        "schedule_type": "immediate",
        "scheduled_at": null,
        "subject_lines": [
            "Quick question, {{first_name|there}}"
        ],
        "email_bodies": [
            "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..."
        ],
        "send_window": {
            "start": "09:00",
            "end": "17:00",
            "days": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri"
            ],
            "timezone": "Europe/London"
        },
        "follow_up": {
            "enabled": true,
            "delay_days": 3,
            "max": 3
        },
        "stop_on_reply": true,
        "stats": {
            "total_leads": 240,
            "sent": 0,
            "opened": 0,
            "clicked": 0,
            "replied": 0,
            "bounced": 0
        },
        "created_at": "2026-09-20T08:00:00Z"
    }
}

Pause a campaign

POST/api/v1/campaigns/{id}/pause

Stops sending until resumed. Nothing is lost.

Needs a read and write API key.

Parameters

NameTypeDescription
idrequired path uuid Campaign id.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X POST https://app.zicreach.com/api/v1/campaigns/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10/pause \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "message": "Campaign paused.",
    "data": {
        "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "name": "Q4 founders",
        "status": "paused",
        "campaign_type": "standard",
        "schedule_type": "immediate",
        "scheduled_at": null,
        "subject_lines": [
            "Quick question, {{first_name|there}}"
        ],
        "email_bodies": [
            "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..."
        ],
        "send_window": {
            "start": "09:00",
            "end": "17:00",
            "days": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri"
            ],
            "timezone": "Europe/London"
        },
        "follow_up": {
            "enabled": true,
            "delay_days": 3,
            "max": 3
        },
        "stop_on_reply": true,
        "stats": {
            "total_leads": 240,
            "sent": 0,
            "opened": 0,
            "clicked": 0,
            "replied": 0,
            "bounced": 0
        },
        "created_at": "2026-09-20T08:00:00Z"
    }
}

Resume a campaign

POST/api/v1/campaigns/{id}/resume

Continues a paused campaign.

Needs a read and write API key.

Parameters

NameTypeDescription
idrequired path uuid Campaign id.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X POST https://app.zicreach.com/api/v1/campaigns/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10/resume \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "message": "Campaign resumed.",
    "data": {
        "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
        "name": "Q4 founders",
        "status": "active",
        "campaign_type": "standard",
        "schedule_type": "immediate",
        "scheduled_at": null,
        "subject_lines": [
            "Quick question, {{first_name|there}}"
        ],
        "email_bodies": [
            "Hi {{first_name|there}},\n\nNoticed {{company}} is hiring..."
        ],
        "send_window": {
            "start": "09:00",
            "end": "17:00",
            "days": [
                "mon",
                "tue",
                "wed",
                "thu",
                "fri"
            ],
            "timezone": "Europe/London"
        },
        "follow_up": {
            "enabled": true,
            "delay_days": 3,
            "max": 3
        },
        "stop_on_reply": true,
        "stats": {
            "total_leads": 240,
            "sent": 0,
            "opened": 0,
            "clicked": 0,
            "replied": 0,
            "bounced": 0
        },
        "created_at": "2026-09-20T08:00:00Z"
    }
}

List campaign recipients

GET/api/v1/campaigns/{id}/leads

Recipients and where each one is in the sequence.

Any API key, read-only included.

Parameters

NameTypeDescription
idrequired path uuid Campaign id.
status query string pending, active, sent, replied, bounced, unsubscribed or completed.
per_page query integer Up to 200. Default 50.

Errors

  • 401Missing or invalid key
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl https://app.zicreach.com/api/v1/campaigns/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10/leads \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "data": [
        {
            "id": "9d1c6a2f-8a3e-41c7-b2d4-6e5f0a9c1b22",
            "email": "jane@example.com",
            "first_name": "Jane",
            "last_name": "Doe",
            "company": "Example Ltd",
            "status": "active",
            "current_step": 1,
            "last_sent_at": "2026-09-22T09:14:00Z",
            "opened_at": null,
            "clicked_at": null,
            "replied_at": null,
            "bounced_at": null
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 1,
        "total": 1
    }
}

Add leads to a campaign

POST/api/v1/campaigns/{id}/leads

Adds a whole list (optionally filtered) or specific leads. Suppressed addresses, duplicates and people contacted too recently are skipped.

Needs a read and write API key.

Parameters

NameTypeDescription
idrequired path uuid Campaign id.

Body

NameTypeDescription
list_id uuid Add the leads of this list. Required unless lead_ids is sent.
lead_ids uuid[] Add these leads, up to 1,000. Required unless list_id is sent.
company string With list_id: only leads at this company.
industry string With list_id: only this industry.
job_title string With list_id: only titles containing this.
location string With list_id: only this location.

Errors

  • 401Missing or invalid key
  • 403Read-only key used for a change, or a key made by someone who is no longer an owner or admin
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl -X POST https://app.zicreach.com/api/v1/campaigns/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10/leads \
  -H "Authorization: Bearer zk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"list_id":"9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10"}'
Response200
{
    "data": {
        "added": 240,
        "skipped": 12,
        "cooling": 3,
        "total_recipients": 240
    }
}

Get campaign stats

GET/api/v1/campaigns/{id}/stats

Totals, rates, A/B variants and the last 14 days of sends for one campaign.

Any API key, read-only included.

Parameters

NameTypeDescription
idrequired path uuid Campaign id.

Errors

  • 401Missing or invalid key
  • 404Not found in this workspace
  • 422Invalid input, or not ready; the body has message and an errors object, one entry per field
  • 429More than 120 requests a minute
Request
curl https://app.zicreach.com/api/v1/campaigns/9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10/stats \
  -H "Authorization: Bearer zk_your_key"
Response200
{
    "data": {
        "campaign": {
            "id": "9d1c6a2e-4b7f-4e0a-9a51-2f8c3b6d7e10",
            "name": "Q4 founders",
            "status": "active"
        },
        "totals": {
            "recipients": 240,
            "sent": 212,
            "delivered": 209,
            "opened": 71,
            "clicked": 8,
            "replied": 6,
            "bounced": 3,
            "unsubscribed": 1,
            "pending": 28,
            "failed": 0
        },
        "rates": {
            "open": 34,
            "click": 3.8,
            "reply": 2.9,
            "bounce": 1.4,
            "unsubscribe": 0.5,
            "progress": 88.3
        },
        "variants": [
            {
                "index": 0,
                "subject": "Quick question, {{first_name|there}}",
                "sent": 212,
                "replied": 6,
                "reply_rate": 2.9
            }
        ],
        "daily": [
            {
                "date": "2026-09-24",
                "sent": 40
            }
        ]
    }
}