Skip to content
Docs

Campaigns

Create campaigns, choose their audiences and segments, and send or schedule them.

Base URLhttps://api.emailit.com/v2AuthenticationErrorsRate limits

Create a campaign

Creates a campaign in draft status. Requires an API key with the full scope. Emits a campaign.created event.

A new campaign has no recipients. Choose its audiences and segments with Update a campaign, then send or schedule it. Credits are charged when the campaign sends: 2 credits per email.

POST/campaigns

Body parameters

namestringrequired
Internal name of the campaign. Recipients don’t see it. Other campaign endpoints accept the name in place of the ID, so keep names unique if you use them that way.
subjectstring
Subject line. Supports merge tags such as {{first_name}}.
from_emailstring
Sender address. It must be on a verified sending domain in the workspace, for example news@acme.com.
from_namestring
Sender display name, for example Acme. The message is sent from Acme <news@acme.com>.
reply_tostring
Reply-To address. Defaults to from_email when the campaign sends.
htmlstring
HTML body that Emailit sends, rendered with Temple for each recipient. Supports the merge tags {{first_name}}, {{last_name}}, {{email}}, {{unsubscribe_url}} and {{cf.<key>}} for custom fields, with fallbacks and {{#if}} blocks. Set the body when you create the campaign.
textstring
Plain-text body. Supports the same merge tags as html.
preview_textstring
Preview text that inboxes show after the subject. Supports merge tags. When the campaign sends, Emailit adds it as hidden text at the top of the HTML body, unless the HTML already contains the same text in a hidden element (for example from an MJML <mj-preview>).
contentstring
Editor source of the body (for example MJML), stored as-is. If you pass neither html nor text and content_type is html or text, Emailit sends content as the HTML or plain-text body.
content_typestringdefault: html
Format of content: html, text or mjml. For the Emailit team, Emailit compiles mjml content into html (alpha). For everyone else mjml is a label: send the compiled HTML in html.
utm_trackingbooleandefault: false
Set to true to add UTM parameters to every http and https link when the campaign sends, so your web analytics credit the campaign. Parameters a link already has are kept, and unsubscribe and web version links aren’t changed. See Sending options.
utm_paramsobject | null

UTM values to use when utm_tracking is on. Each key sets one utm_ parameter:

  • source (default emailit), medium (default email) and campaign (default {campaign_name}).
  • content, term and id, not added by default.

Values are text up to 191 characters and can contain the tokens {campaign_name} (the campaign name in lowercase, with dashes), {campaign_id}, {subject}, {variant} (the A/B test variant name) and {send_date} (YYYY-MM-DD). Unknown keys and tokens return 422. Keys you don’t set keep their defaults; null or {} resets all of them.

smart_sending_hoursinteger | null
Skip contacts that another campaign of the workspace emailed in the last this many hours, from 1 to 168. null (default) turns smart sending off. Checked when the campaign starts sending. Emails from automations and the Email API don’t count.
exclude_unengagedbooleandefault: false
Set to true to skip contacts who were sent 3 or more campaign emails in the last 90 days and opened or clicked none of them.
tagsstring[]
Labels for organizing campaigns. Up to 20 tags of up to 50 characters each. Empty tags are dropped and duplicates are removed, ignoring case. Sending tags replaces the list.
send_strategystringdefault: immediate
How the send is spread over time: immediate, throttled, local_time or smart_time. Stored with the campaign and used when you send it without a strategy.
send_optionsobject | null
Options of send_strategy, stored as given and checked in full when the campaign is sent. See Send or schedule a campaign.
ab_testobject | null

An A/B test of 2 to 5 variants. A random share of the recipients is split evenly across the variants. After duration_hours, the rest of the recipients get the variant with the best result. While the test runs, the campaign’s status is testing. A/B tests send with the immediate strategy, now or at a scheduled time.

  • enabled (boolean, default true): false turns the test off.
  • winner_metric (string, default opened): opened, clicked, orders (credited orders per email sent) or revenue (credited revenue per email sent). orders and revenue are part of Commerce, which is in alpha: other requests return 403 with error: "commerce_alpha".
  • test_size_percent (integer, default 20): share of the recipients in the test, from 10 to 100. At 100, everyone is in the test and no winner is sent.
  • duration_hours (integer, default 4): how long the test runs before the winner is sent, from 1 to 168.
  • variants (object[], required): 2 to 5 variants. Each can set name (up to 100 characters, defaults to A, B, C and so on), subject, preview_text, from_name, from_email, reply_to, html and text. Fields a variant leaves out come from the campaign. At least one variant must set a subject, preview text, sender name or address, or body.

Returns

Returns 201 Created with the campaign object. status is draft. The response doesn’t echo html, text or content. It includes the settings above, send_completes_at and send_summary (both null until the campaign sends), and ab_test with the variants and their IDs (cvr_…). See Retrieve a campaign.

Returns 400 if name is missing, 403 if the API key doesn’t have the full scope, and 422 if a setting or the A/B test is invalid.

POST/campaigns
Terminal
curl -X POST https://api.emailit.com/v2/campaigns \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October newsletter",
    "subject": "October news for {{first_name}}",
    "from_email": "news@acme.com",
    "from_name": "Acme",
    "reply_to": "support@acme.com",
    "html": "<p>Hi {{first_name}},</p><p>Here is what changed this month.</p><p><a href=\"{{unsubscribe_url}}\">Unsubscribe</a></p>",
    "text": "Hi {{first_name}}, here is what changed this month. Unsubscribe: {{unsubscribe_url}}"
  }'
JSON
{
  "object": "campaign",
  "id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
  "name": "October newsletter",
  "status": "draft",
  "subject": "October news for {{first_name}}",
  "from_email": "news@acme.com",
  "from_name": "Acme",
  "reply_to": "support@acme.com",
  "preview_text": null,
  "content_type": "html",
  "created_at": "2026-10-01T09:30:12.482193Z",
  "updated_at": "2026-10-01T09:30:12.482193Z",
  "utm_tracking": false,
  "utm_params": null,
  "smart_sending_hours": null,
  "exclude_unengaged": false,
  "tags": [],
  "send_strategy": "immediate",
  "send_options": null,
  "send_completes_at": null,
  "send_summary": null,
  "ab_test": {
    "enabled": false,
    "variants": []
  }
}

Retrieve a campaign

Retrieves a campaign by its ID or name. Requires an API key with the full scope.

GET/campaigns/{id}

Path parameters

idstringrequired
The campaign ID (cmp_…) or the campaign name. URL-encode names that contain spaces or special characters.

Returns

Returns the campaign object.

objectstring
Always campaign.
idstring
Campaign ID, prefixed cmp_.
statusstring
draft, scheduled, queued, sending, testing, sent, canceled or archived. queued means a scheduled campaign has reached its send time and is waiting for a worker. testing means an A/B test is running and the winner hasn’t been sent yet. A send spread over time stays sending until its last batch is due.
namestring
Internal campaign name.
subjectstring
Subject line, with merge tags unresolved.
from_emailstring
Sender address. "" until set.
from_namestring
Sender display name. "" until set.
reply_tostring
Reply-To address. "" means replies go to from_email.
preview_textstring | null
Preview text that inboxes show after the subject.
content_typestring
Format label of the editor source: html, text or mjml for campaigns created through the API. Campaigns whose MJML Emailit compiled (alpha) also return an mjml object with the document’s versions.
scheduled_atstring | null
When a scheduled campaign sends, in UTC.
sent_atstring | null
When sending started.
utm_trackingboolean
Whether UTM parameters are added to the campaign’s links.
utm_paramsobject | null
UTM values that replace the defaults, or null. See Create a campaign.
smart_sending_hoursinteger | null
Contacts that another campaign emailed in the last this many hours are skipped. null when smart sending is off.
exclude_unengagedboolean
Whether contacts who were sent 3 or more campaign emails in the last 90 days and opened or clicked none of them are skipped.
tagsstring[]
The campaign’s tags.
send_strategystring
immediate, throttled, local_time or smart_time.
send_optionsobject | null
Options of the strategy. See Send or schedule a campaign.
send_completes_atstring | null
For a send spread over more than a minute, when its last batch is due. The campaign changes to sent after that.
send_summaryobject | null

What the last send did, or null before the campaign sends:

  • recipients: contacts in the audiences and segments, once per address.
  • suppressed: skipped because the address is suppressed.
  • smart_sending_skipped: skipped by smart_sending_hours.
  • unengaged_skipped: skipped by exclude_unengaged.
  • sent: contacts the campaign was sent to. For an A/B test, the test group only.
  • batches: number of sending batches.
  • completes_at: same as send_completes_at.
ab_testobject

The A/B test. Without a test: { "enabled": false, "variants": [] }. With a test: enabled, winner_metric, test_size_percent, duration_hours and variants. Each variant has id (cvr_…), name, subject, preview_text, from_name, from_email, reply_to, html, text (null when the variant uses the campaign’s value) and is_winner. See Create a campaign.

recipientsobject[]
Audiences and segments the campaign targets. Each item has either audience_id (aud_…) or segment_id (seg_…), and exclude (true for an exclusion).

The body (html, text and content) isn’t included in the response. For engagement and revenue, use Retrieve campaign statistics or the report in the dashboard under Email MarketingCampaigns.

Returns 404 if no campaign in the workspace matches id.

GET/campaigns/{id}
Terminal
curl https://api.emailit.com/v2/campaigns/cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "campaign",
  "id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
  "name": "October newsletter",
  "status": "scheduled",
  "subject": "October news for {{first_name}}",
  "from_email": "news@acme.com",
  "from_name": "Acme",
  "reply_to": "support@acme.com",
  "preview_text": null,
  "content_type": "html",
  "sent_at": null,
  "scheduled_at": "2026-10-08 09:00:00+00",
  "created_at": "2026-10-01 09:30:12.482193+00",
  "updated_at": "2026-10-01 10:02:47.118204+00",
  "utm_tracking": true,
  "utm_params": {
    "campaign": "{campaign_name}-{send_date}"
  },
  "smart_sending_hours": 16,
  "exclude_unengaged": true,
  "tags": ["newsletter", "q4"],
  "send_strategy": "throttled",
  "send_options": {
    "per_hour": 5000
  },
  "send_completes_at": null,
  "send_summary": null,
  "ab_test": {
    "enabled": false,
    "variants": []
  },
  "recipients": [
    { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV", "exclude": false },
    { "segment_id": "seg_3Kq8VbN2xYt5Lm9Pw1Rc7Hd4Zf0", "exclude": true }
  ]
}

Update a campaign

Updates the fields you pass and leaves the others unchanged. Use it to choose the campaign’s audiences and segments before you send it. Requires an API key with the full scope. Emits a campaign.updated event.

A scheduled campaign sends whatever is saved at its send time, so you can still edit it after scheduling.

POST/campaigns/{id}

Path parameters

idstringrequired
The campaign ID (cmp_…) or the campaign name.

Body parameters

namestring
Internal campaign name.
subjectstring
Subject line. Supports merge tags.
from_emailstring
Sender address on a verified sending domain.
from_namestring
Sender display name.
reply_tostring
Reply-To address. An empty string means replies go to from_email.
preview_textstring
Preview text that inboxes show after the subject. Emailit adds it as hidden text at the top of the HTML body when the campaign sends. See Create a campaign.
contentstring
Editor source of the body, stored as-is. When you change content or content_type and the format is html or text, Emailit sends content as the new HTML or plain-text body.
content_typestring
Format of content: html, text or mjml. For the Emailit team, Emailit compiles mjml content into html (alpha). For everyone else mjml is a label.
utm_trackingboolean
Add UTM parameters to the campaign’s links when it sends. See Create a campaign.
utm_paramsobject | null
UTM values: source, medium, campaign, content, term and id. Replaces the stored object; null restores the defaults. See Create a campaign.
smart_sending_hoursinteger | null
Skip contacts that another campaign emailed in the last this many hours, from 1 to 168. null turns it off.
exclude_unengagedboolean
Skip contacts who were sent 3 or more campaign emails in the last 90 days and opened or clicked none of them.
tagsstring[]
Up to 20 tags of up to 50 characters each. Replaces the current tags.
send_strategystring
immediate, throttled, local_time or smart_time. Used when you send the campaign without a strategy.
send_optionsobject | null
Options of send_strategy, checked in full when the campaign is sent. See Send or schedule a campaign.
ab_testobject | null

The A/B test, with the fields described in Create a campaign. Sending ab_test replaces the test and its variants. To keep a variant’s ID, and with it the variant’s results, include its id (cvr_…) in the variant. null or "enabled": false turns the test off and deletes the variants.

recipientsobject[]

The audiences and segments to target, up to 100 items. Replaces the current list. Include at least one item with exclude set to false. Each item has either audience_id or segment_id, not both:

  • audience_id (string): an audience ID (aud_…) in this workspace.
  • segment_id (string): a segment ID (seg_…) in this workspace. Segments are in alpha: only the Emailit team can add one, and other requests return 403 with error: "segments_alpha". Segments the campaign already has can be kept.
  • exclude (boolean, default false): true leaves out the audience’s subscribers or the segment’s contacts, even if they’re also in an included item.

Duplicate items are ignored. At send time, Emailit emails each contact once if it’s subscribed to an included audience or matches an included segment, isn’t in an excluded one, isn’t globally unsubscribed, is subscribed to at least one audience, and isn’t suppressed. Segments are evaluated at send time. If an excluded audience or segment no longer exists by then, the campaign isn’t sent.

The HTML and text body are set when you create the campaign. Unknown body fields are ignored.

Returns

Returns the updated campaign object, including recipients and ab_test. See Retrieve a campaign.

Returns 422 if recipients has no included audience or segment, has more than 100 items, has an item with both IDs, or references an audience or segment outside the workspace. Also returns 422 when a setting or the A/B test is invalid, or when you send ab_test for a campaign that isn’t a draft or scheduled, and 404 if the campaign doesn’t exist.

POST/campaigns/{id}
Terminal
curl -X POST https://api.emailit.com/v2/campaigns/cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Your October update, {{first_name}}",
    "recipients": [
      { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV" },
      { "segment_id": "seg_3Kq8VbN2xYt5Lm9Pw1Rc7Hd4Zf0", "exclude": true }
    ]
  }'
JSON
{
  "object": "campaign",
  "id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
  "name": "October newsletter",
  "status": "draft",
  "subject": "Your October update, {{first_name}}",
  "from_email": "news@acme.com",
  "from_name": "Acme",
  "reply_to": "support@acme.com",
  "preview_text": null,
  "content_type": "html",
  "scheduled_at": null,
  "created_at": "2026-10-01 09:30:12.482193+00",
  "updated_at": "2026-10-01 10:02:47.118204+00",
  "utm_tracking": false,
  "utm_params": null,
  "smart_sending_hours": null,
  "exclude_unengaged": false,
  "tags": [],
  "send_strategy": "immediate",
  "send_options": null,
  "send_completes_at": null,
  "send_summary": null,
  "ab_test": {
    "enabled": false,
    "variants": []
  },
  "recipients": [
    { "audience_id": "aud_3Cz7WJ9GpvD7P0PQez50xOmkZSV", "exclude": false },
    { "segment_id": "seg_3Kq8VbN2xYt5Lm9Pw1Rc7Hd4Zf0", "exclude": true }
  ]
}

List campaigns

Returns the workspace’s campaigns, newest first. Requires an API key with the full scope.

GET/campaigns

Query parameters

pageintegerdefault: 1
Page number, starting at 1.
limitintegerdefault: 10
Campaigns per page, from 1 to 100.
statusstring
Shortcut status filter: draft, scheduled, sending (also matches queued), sent, canceled, archived or all.
matchstring

all (default) requires every filter. or matches any filter. See Filtering.

orderstring

Sort key for this list. See the sort keys below.

directionstring

asc or desc.

Filter keys

Filters use key.condition=value query parameters, for example status.exact=sent or created_at.after=2026-09-01. See Filtering for the conditions per type.

Key Type Notes
name string
subject string
status enum draft, scheduled, queued, sending, sent, archived
created_at date
sent_at date

Sort keys for order: name, subject, status, created_at, sent_at.

Returns

Returns a page of campaign objects without reply_to, preview_text, content_type and recipients, and with only tags, send_strategy and send_completes_at of the sending options. Use Retrieve a campaign for the rest.

dataobject[]
Campaigns on this page.
total_recordsinteger
Number of campaigns that match the query.
next_page_urlstring | null
Path of the next page, or null on the last page. It carries only page and limit, so add your search and filters again when you follow it.
previous_page_urlstring | null
Path of the previous page, or null on the first page.
GET/campaigns
Terminal
curl -G https://api.emailit.com/v2/campaigns \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d limit=20 \
  -d status=sent \
  -d order=sent_at \
  -d direction=desc
JSON
{
  "data": [
    {
      "object": "campaign",
      "id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
      "name": "October newsletter",
      "status": "sent",
      "subject": "Your October update, {{first_name}}",
      "from_email": "news@acme.com",
      "from_name": "Acme",
      "sent_at": "2026-10-08 09:00:04+00",
      "scheduled_at": "2026-10-08 09:00:00+00",
      "created_at": "2026-10-01 09:30:12.482193+00",
      "updated_at": "2026-10-08 09:00:31+00",
      "tags": ["newsletter"],
      "send_strategy": "immediate",
      "send_completes_at": null
    }
  ],
  "total_records": 34,
  "next_page_url": "/v2/campaigns?page=2&limit=20",
  "previous_page_url": null
}

Send or schedule a campaign

Sends the campaign now, or schedules it when you pass a future scheduled_at. Requires an API key with the full scope and a verified workspace: unverified workspaces can’t send campaigns and get 403. Only drafts and scheduled campaigns can be sent: a campaign that is sending or was sent returns 422, so a retried request doesn’t email everyone again.

Before you send, make sure the campaign has a from_email on a verified domain, a subject, an html or text body, and at least one included audience or segment (set with Update a campaign). Each email costs 2 credits.

POST/campaigns/{id}/send

Path parameters

idstringrequired
The campaign ID (cmp_…) or the campaign name.

Body parameters

scheduled_atstring

When to send. Accepts ISO 8601 (2026-10-08T09:00:00Z), a Unix timestamp in seconds, or natural language such as tomorrow at 9am (interpreted in UTC). The time must be in the future and the campaign must be a draft.

Omit it to send now. To send a scheduled campaign early, call this endpoint without scheduled_at.

send_strategystring

How to spread the send over time. Defaults to the strategy saved on the campaign, else immediate. The strategy and its options are saved on the campaign. See Sending options.

  • immediate: everyone at once, now or at scheduled_at.
  • throttled: an even pace of per_hour emails, starting now or at scheduled_at.
  • local_time: a wall-clock time in each contact’s time zone. scheduled_at is ignored.
  • smart_time: each contact at the hour they usually open or click, within a window from the start.

Campaigns with an A/B test only send with immediate.

send_optionsobject

Options of the strategy. Defaults to the options saved on the campaign.

  • throttled: per_hour (integer, required), from 100 to 1,000,000 emails per hour.
  • local_time: local_time (string, required), the time as YYYY-MM-DDTHH:mm, for example 2026-10-08T09:00, and timezone (string, default UTC), the IANA time zone for contacts whose time zone isn’t known. Contacts’ time zones come from the tracking script. Sending starts when the earliest time zone (UTC+14) reaches the time; contacts in zones already past it get the email right away. Until then the campaign is scheduled, so it must be a draft. Returns 422 when the time has passed in every time zone.
  • smart_time: window_hours (integer, default 24), from 1 to 48. Each contact gets the email at the hour of day (UTC) they opened or clicked most in the last 90 days, with a click counting three times as much as an open, when that hour comes within the window. Contacts without that history get the hour most common among the other recipients. Contacts with neither, or whose hour falls outside the window, get it at the start.

timezone is accepted with every strategy and must be a valid IANA time zone, but only local_time uses it.

Returns

Send now: the status changes to sending and Emailit emits campaign.sending. Emailit then resolves the recipients: every subscribed contact of the included audiences and every contact matching the included segments, once per address, without contacts in excluded audiences or segments, contacts that are globally unsubscribed or on no audience, and suppressed addresses. Segments are evaluated at this moment. It also skips contacts left out by smart_sending_hours and exclude_unengaged. The emails are created at the times the send strategy sets. Once every recipient has been handed to the sending pipeline, the status changes to sent and Emailit emits campaign.sent. A send spread over time stays sending until its last batch is due (send_completes_at). The campaign’s send_summary shows how many contacts were sent the campaign and how many were skipped. Track delivery in the dashboard, with Retrieve campaign statistics or with email events.

A/B test: the test group gets the variants and the status changes to testing. After duration_hours, the rest of the recipients get the winning variant and the status changes to sent.

Schedule: the status changes to scheduled and Emailit emits campaign.scheduled. At the scheduled time the campaign becomes queued (campaign.queued) and then sends as above. If an excluded audience or segment was deleted in the meantime, the campaign goes back to draft instead of sending.

The response contains object, id, name and the new status, plus scheduled_at when you schedule.

Status When
403 The workspace isn’t verified, or the API key doesn’t have the full scope.
404 No campaign matches id.
422 The campaign is neither a draft nor scheduled (for example, it’s sending or was sent), scheduled_at can’t be parsed or isn’t in the future, you tried to schedule a campaign that isn’t a draft, the campaign has no html or text body, it has no recipients (set them with Update a campaign), it excludes an audience or segment that no longer exists, or send_strategy and send_options are invalid. The error for the strategy names the field in message.
POST/campaigns/{id}/send
Terminal
curl -X POST https://api.emailit.com/v2/campaigns/cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN/send \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-10-08T09:00:00Z" }'
JSON
{
  "object": "campaign",
  "id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
  "name": "October newsletter",
  "status": "scheduled",
  "scheduled_at": "2026-10-08T09:00:00.000000Z"
}

Cancel a campaign

Sets the campaign’s status to canceled and emits a campaign.canceled event. Requires an API key with the full scope.

Only campaigns in draft or sending status can be canceled; any other status returns 422. Canceling a campaign that is sending doesn’t recall emails that are already queued for delivery.

POST/campaigns/{id}/cancel

Path parameters

idstringrequired
The campaign ID (cmp_…) or the campaign name.

Returns

Returns object, id, name and status (canceled).

Returns 422 if the campaign’s status isn’t draft or sending, and 404 if the campaign doesn’t exist.

POST/campaigns/{id}/cancel
Terminal
curl -X POST https://api.emailit.com/v2/campaigns/cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN/cancel \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "campaign",
  "id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
  "name": "October newsletter",
  "status": "canceled"
}

Retrieve campaign statistics

Retrieve the report of a campaign: how many emails were sent, delivered, opened and clicked, the results per mailbox provider, the revenue of the orders credited to the campaign (Commerce, alpha) and, for A/B tests, the results per variant. The dashboard report under Email MarketingCampaigns shows the same numbers. Requires an API key with the full scope.

Every count is a number of emails: an email that was opened three times counts once in opened. Percentages are relative to sent unless noted, with two decimal places.

GET/campaigns/{id}/stats

Path parameters

idstringRequired

The campaign ID (cmp_...) or the campaign name. URL-encode names that contain spaces or special characters.

Query parameters

fromstring

Only count emails created at or after this time, an ISO 8601 date or date-time.

tostring

Only count emails created at or before this time.

statusstring

Only count emails whose current status is this one: accepted, scheduled, delivered, loaded, clicked, attempted, bounced, failed, rejected, suppressed or complained. Other values are ignored.

The filters apply to the email counts, the providers and the A/B test counts, and from and to also apply to unsubscribed. Revenue, orders and buyers always cover every order credited to the campaign, and their rates use all of the campaign’s delivered emails.

Returns

objectstring

Always campaign_stats.

campaign_idstring

The campaign ID (cmp_...).

sentinteger

Emails created for the campaign. sent_percent is 100, or 0 before anything is sent.

delivered, delivered_percentinteger, number

Emails whose status is delivered, loaded or clicked.

opened, opened_percentinteger, number

Emails opened at least once.

clicked, clicked_percentinteger, number

Emails with at least one tracked click.

click_through_percentnumber

clicked as a percentage of opened.

bounced, suppressed, complained, attemptedinteger

Emails whose status is bounced, suppressed, complained or attempted (waiting for a retry). Each has a _percent field too.

not_processed, not_processed_percentinteger, number

Emails still accepted or scheduled.

unsubscribed, unsubscribed_percentinteger, number

Unsubscribes from the campaign’s emails.

providersobject[]

Results per mailbox provider of the recipients, for providers with at least one email. key is gmail, outlook.com, live.com, hotmail.com, yahoo, icloud or other, and label is its display name. Each has sent, delivered, opened, clicked and bounced with their _percent fields. sent_percent is the provider’s share of all emails; the other percentages are relative to the provider’s sent.

commerceobject

Only for the Emailit team while Commerce is in alpha: other requests don’t get this field, and their A/B variants leave out orders, revenue and revenue_per_recipient. Orders credited to the campaign. Revenue is the order total minus refunds, and canceled orders don’t count. Amounts in different currencies aren’t added up: the main currency is the one with the most revenue.

  • currency (string or null): the main currency.

  • revenue (number): revenue in the main currency.

  • orders (integer): credited orders in all currencies.

  • buyers (integer): distinct buyers in all currencies. A buyer who paid in two currencies counts once.

  • average_order_value (number): in the main currency.

  • conversion_percent (number): buyers as a percentage of the campaign’s delivered emails.

  • revenue_per_recipient (number): revenue divided by the campaign’s delivered emails.

  • by_currency (object[]): currency, orders, revenue, buyers and average_order_value for each currency, highest revenue first.

ab_testobject

Only for campaigns with an A/B test.

  • winner_metric (string): opened, clicked, orders or revenue.

  • leader_variant_id (string or null): the variant with the best rate so far: opens, clicks or orders per email sent, or revenue per email sent.

  • win_probability (number or null): the chance, in percent, that the leader really beats the runner-up.

  • significance (string): significant (90% or more, with at least 50 emails per variant), promising (75% or more, same minimum), not_significant (under 75% with at least 1,800 emails per variant) or inconclusive. For revenue, the probability is based on orders.

  • variants (object[]): per variant variant_id, name, subject, is_winner, sent, delivered, opened, opened_percent, clicked, clicked_percent, orders, revenue and revenue_per_recipient. Once the winner is sent to the rest of the audience, the winning variant’s counts include those emails.

Returns 404 if no campaign matches id, and 503 when the analytics store isn’t available.

GET/campaigns/{id}/stats
Terminal
curl https://api.emailit.com/v2/campaigns/cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN/stats \
  -H "Authorization: Bearer your_api_key"
JSON
{
  "object": "campaign_stats",
  "campaign_id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
  "sent": 12480,
  "sent_percent": 100,
  "delivered": 12302,
  "delivered_percent": 98.57,
  "opened": 5021,
  "opened_percent": 40.23,
  "clicked": 1187,
  "clicked_percent": 9.51,
  "click_through_percent": 23.64,
  "bounced": 98,
  "bounced_percent": 0.79,
  "suppressed": 42,
  "suppressed_percent": 0.34,
  "complained": 3,
  "complained_percent": 0.02,
  "attempted": 0,
  "attempted_percent": 0,
  "not_processed": 38,
  "not_processed_percent": 0.3,
  "unsubscribed": 27,
  "unsubscribed_percent": 0.22,
  "providers": [
    {
      "key": "gmail",
      "label": "Gmail",
      "sent": 7310,
      "sent_percent": 58.57,
      "delivered": 7236,
      "delivered_percent": 98.99,
      "opened": 3102,
      "opened_percent": 42.44,
      "clicked": 741,
      "clicked_percent": 10.14,
      "bounced": 41,
      "bounced_percent": 0.56
    },
    {
      "key": "other",
      "label": "Other",
      "sent": 5170,
      "sent_percent": 41.43,
      "delivered": 5066,
      "delivered_percent": 97.99,
      "opened": 1919,
      "opened_percent": 37.12,
      "clicked": 446,
      "clicked_percent": 8.63,
      "bounced": 57,
      "bounced_percent": 1.1
    }
  ],
  "commerce": {
    "currency": "USD",
    "revenue": 17311.9,
    "orders": 214,
    "buyers": 198,
    "average_order_value": 86.13,
    "conversion_percent": 1.61,
    "revenue_per_recipient": 1.41,
    "by_currency": [
      {
        "currency": "USD",
        "orders": 201,
        "revenue": 17311.9,
        "buyers": 186,
        "average_order_value": 86.13
      },
      {
        "currency": "EUR",
        "orders": 13,
        "revenue": 1052.4,
        "buyers": 12,
        "average_order_value": 80.95
      }
    ]
  }
}

Delete a campaign

Permanently deletes a campaign. Requires an API key with the full scope. Emits a campaign.deleted event.

Deleting a campaign doesn’t affect emails that were already sent or queued. To stop a campaign that is sending, cancel it first.

DELETE/campaigns/{id}

Path parameters

idstringrequired
The campaign ID (cmp_…) or the campaign name.

Returns

Returns object, id, name and deleted: true. Returns 404 if the campaign doesn’t exist.

DELETE/campaigns/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/campaigns/cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "campaign",
  "id": "cmp_3zNrBaNjAoPK1l0IL2GQ3pDkubN",
  "name": "October newsletter",
  "deleted": true
}

Was this page helpful?

Thanks for the feedback.

Thanks, we read every message.

Esc

Popular

↑↓to navigate↵to openEscto close