Přejít na obsah
Dokumentace

Kampaně

Vytvářejte kampaně, vybírejte pro ně seznamy kontaktů a segmenty a kampaně odešlete hned, nebo je naplánujte.

Základní URLhttps://api.emailit.com/v2AutentizaceChybyLimity rychlosti

Vytvoření kampaně

Vytvoří kampaň ve stavu draft. Vyžaduje API klíč s oprávněním full. Vyvolá událost campaign.created.

Nová kampaň nemá žádné příjemce. Seznamy kontaktů a segmenty pro ni vyberte endpointem Úprava kampaně a potom ji odešlete nebo naplánujte. Kredity se účtují při odeslání kampaně: 2 kredity za e-mail.

POST/campaigns

Parametry v těle požadavku

namestringpovinné
Interní název kampaně. Příjemci ho nevidí. Ostatní endpointy kampaní přijímají místo ID i název, takže pokud je tak používáte, dbejte, aby názvy byly jedinečné.
subjectstring
Předmět. Podporuje slučovací značky, například {{first_name}}.
from_emailstring
Adresa odesílatele. Musí být na ověřené odesílací doméně ve workspace, například news@acme.com.
from_namestring
Zobrazované jméno odesílatele, například Acme. Zpráva se odešle od Acme <news@acme.com>.
reply_tostring
Adresa pro odpověď. Pokud ji nenastavíte, použije se při odeslání kampaně from_email.
htmlstring
Tělo v HTML, které Emailit pro každého příjemce vykreslí jazykem Temple a odešle. Podporuje slučovací značky {{first_name}}, {{last_name}}, {{email}}, {{unsubscribe_url}} a {{cf.<key>}} pro vlastní pole, s náhradními hodnotami a bloky {{#if}}. Tělo nastavte při vytváření kampaně.
textstring
Tělo v prostém textu. Podporuje stejné slučovací značky jako html.
preview_textstring
Text náhledu, který schránky zobrazují za předmětem. Podporuje slučovací značky. Při odeslání kampaně ho Emailit přidá jako skrytý text na začátek těla v HTML, pokud HTML už stejný text neobsahuje ve skrytém prvku (například z MJML <mj-preview>).
contentstring
Zdroj těla z editoru (například MJML), uložený beze změny. Když nepředáte html ani text a content_type je html nebo text, Emailit odešle content jako tělo v HTML nebo v prostém textu.
content_typestringvýchozí: html
Formát content: html, text nebo mjml. Pro tým Emailitu Emailit zkompiluje obsah mjml do html (alfaverze). Pro všechny ostatní je mjml jen označení: zkompilované HTML pošlete v html.
utm_trackingbooleanvýchozí: false
Nastavte na true, pokud chcete při odeslání kampaně přidat UTM parametry ke každému odkazu http a https, aby vaše webová analytika připsala návštěvy kampani. Parametry, které odkaz už má, se zachovají, a odkazy pro odhlášení a odkazy na webovou verzi se nemění. Viz Možnosti odesílání.
utm_paramsobject | null

Hodnoty UTM, které se použijí, když je utm_tracking zapnuté. Každý klíč nastavuje jeden parametr utm_:

  • source (výchozí hodnota emailit), medium (výchozí hodnota email) a campaign (výchozí hodnota {campaign_name}).
  • content, term a id, které se ve výchozím stavu nepřidávají.

Hodnoty jsou text o délce nejvýše 191 znaků a mohou obsahovat tokeny {campaign_name} (název kampaně malými písmeny, s pomlčkami), {campaign_id}, {subject}, {variant} (název verze A/B testu) a {send_date} (YYYY-MM-DD). Neznámé klíče a tokeny vrací 422. Klíče, které nenastavíte, si ponechají výchozí hodnoty; null nebo {} obnoví všechny.

smart_sending_hoursinteger | null
Vynechá kontakty, kterým jiná kampaň z workspace poslala e-mail za posledních tolik hodin, od 1 do 168. null (výchozí hodnota) chytré odesílání vypne. Kontroluje se při zahájení odesílání kampaně. E-maily z automatizací a z e-mailového API se nepočítají.
exclude_unengagedbooleanvýchozí: false
Nastavte na true, pokud chcete vynechat kontakty, kterým byly za posledních 90 dní odeslány 3 nebo více e-mailů z kampaní a žádný z nich neotevřely ani v něm neklikly.
tagsstring[]
Štítky pro organizaci kampaní. Až 20 štítků, každý nejvýše 50 znaků. Prázdné štítky se zahodí a duplicity se odstraní bez ohledu na velikost písmen. Odesláním tags se seznam nahradí.
send_strategystringvýchozí: immediate
Jak se odeslání rozloží v čase: immediate, throttled, local_time nebo smart_time. Uloží se s kampaní a použije se, když ji odešlete bez strategie.
send_optionsobject | null
Možnosti strategie send_strategy, uložené tak, jak je zadáte, a úplně zkontrolované až při odeslání kampaně. Viz Odeslání nebo naplánování kampaně.
ab_testobject | null

A/B test se 2 až 5 verzemi. Náhodně vybraný podíl příjemců se rovnoměrně rozdělí mezi verze. Po uplynutí duration_hours dostane zbytek příjemců verzi s nejlepším výsledkem. Během testu je kampaň ve stavu testing. A/B testy se odesílají se strategií immediate, hned, nebo v naplánovaný čas.

  • enabled (boolean, výchozí hodnota true): false test vypne.
  • winner_metric (string, výchozí hodnota opened): opened, clicked, orders (připsané objednávky na odeslaný e-mail) nebo revenue (připsané tržby na odeslaný e-mail). orders a revenue jsou součástí E-commerce, které je v alfaverzi: ostatní požadavky vracejí 403 s error: "commerce_alpha".
  • test_size_percent (integer, výchozí hodnota 20): podíl příjemců v testu, od 10 do 100. Při 100 jsou v testu všichni a žádný vítěz se neodesílá.
  • duration_hours (integer, výchozí hodnota 4): jak dlouho test běží, než se odešle vítěz, od 1 do 168.
  • variants (object[], povinné): 2 až 5 verzí. Každá může nastavit name (nejvýše 100 znaků, výchozí hodnoty A, B, C a tak dále), subject, preview_text, from_name, from_email, reply_to, html a text. Pole, která verze vynechá, se převezmou z kampaně. Aspoň jedna verze musí nastavit předmět, text náhledu, jméno nebo adresu odesílatele, nebo tělo.

Odpověď

Vrací 201 Created s objektem kampaně. status je draft. Odpověď nevrací html, text ani content. Obsahuje nastavení uvedená výše, send_completes_at a send_summary (obojí null, dokud se kampaň neodešle) a ab_test s verzemi a jejich ID (cvr_…). Viz Načtení kampaně.

Pokud chybí name, vrací 400, pokud API klíč nemá oprávnění full, vrací 403, a pokud je některé nastavení nebo A/B test neplatný, vrací 422.

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": []
  }
}

Načtení kampaně

Načte kampaň podle jejího ID nebo názvu. Vyžaduje API klíč s oprávněním full.

GET/campaigns/{id}

Parametry v cestě

idstringpovinné
ID kampaně (cmp_…), nebo název kampaně. Názvy s mezerami nebo speciálními znaky zakódujte pro URL.

Odpověď

Vrací objekt kampaně.

objectstring
Vždy campaign.
idstring
ID kampaně s předponou cmp_.
statusstring
draft, scheduled, queued, sending, testing, sent, canceled nebo archived. queued znamená, že naplánovaná kampaň dosáhla času odeslání a čeká na volný odesílací proces. testing znamená, že probíhá A/B test a vítěz ještě nebyl odeslán. Odeslání rozložené v čase zůstává ve stavu sending, dokud nenastane čas jeho poslední dávky.
namestring
Interní název kampaně.
subjectstring
Předmět s nevyhodnocenými slučovacími značkami.
from_emailstring
Adresa odesílatele. "", dokud není nastavená.
from_namestring
Zobrazované jméno odesílatele. "", dokud není nastavené.
reply_tostring
Adresa pro odpověď. "" znamená, že odpovědi chodí na from_email.
preview_textstring | null
Text náhledu, který schránky zobrazují za předmětem.
content_typestring
Označení formátu zdroje z editoru: u kampaní vytvořených přes API html, text nebo mjml. Kampaně, jejichž MJML zkompiloval Emailit (alfaverze), vracejí navíc objekt mjml s verzemi dokumentu.
scheduled_atstring | null
Kdy se naplánovaná kampaň odešle, v UTC.
sent_atstring | null
Kdy začalo odesílání.
utm_trackingboolean
Zda se k odkazům kampaně přidávají UTM parametry.
utm_paramsobject | null
Hodnoty UTM, které nahrazují výchozí hodnoty, nebo null. Viz Vytvoření kampaně.
smart_sending_hoursinteger | null
Kontakty, kterým jiná kampaň poslala e-mail za posledních tolik hodin, se vynechají. null, když je chytré odesílání vypnuté.
exclude_unengagedboolean
Zda se vynechají kontakty, kterým byly za posledních 90 dní odeslány 3 nebo více e-mailů z kampaní a žádný z nich neotevřely ani v něm neklikly.
tagsstring[]
Štítky kampaně.
send_strategystring
immediate, throttled, local_time nebo smart_time.
send_optionsobject | null
Možnosti strategie. Viz Odeslání nebo naplánování kampaně.
send_completes_atstring | null
U odeslání rozloženého na víc než minutu čas, kdy nastane jeho poslední dávka. Potom kampaň přejde do stavu sent.
send_summaryobject | null

Co udělalo poslední odeslání, nebo null, dokud se kampaň neodešle:

  • recipients: kontakty v seznamech kontaktů a segmentech, každá adresa jednou.
  • suppressed: vynechané, protože je adresa blokovaná.
  • smart_sending_skipped: vynechané kvůli smart_sending_hours.
  • unengaged_skipped: vynechané kvůli exclude_unengaged.
  • sent: kontakty, kterým byla kampaň odeslána. U A/B testu jen testovací skupina.
  • batches: počet odesílacích dávek.
  • completes_at: stejné jako send_completes_at.
ab_testobject

A/B test. Bez testu: { "enabled": false, "variants": [] }. S testem: enabled, winner_metric, test_size_percent, duration_hours a variants. Každá verze má id (cvr_…), name, subject, preview_text, from_name, from_email, reply_to, html, text (null, když verze používá hodnotu kampaně) a is_winner. Viz Vytvoření kampaně.

recipientsobject[]
Seznamy kontaktů a segmenty, na které kampaň cílí. Každá položka má buď audience_id (aud_…), nebo segment_id (seg_…) a k tomu exclude (true u vyloučení).

Tělo (html, text a content) odpověď neobsahuje. Zapojení a tržby zjistíte endpointem Načtení statistik kampaně, nebo v reportu ve webovém rozhraní v sekci Email MarketingCampaigns.

Pokud parametru id neodpovídá žádná kampaň ve workspace, vrací 404.

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 }
  ]
}

Úprava kampaně

Upraví pole, která předáte, a ostatní ponechá beze změny. Použijte ho k výběru seznamů kontaktů a segmentů kampaně před odesláním. Vyžaduje API klíč s oprávněním full. Vyvolá událost campaign.updated.

Naplánovaná kampaň odešle to, co je v čase odeslání uložené, takže ji můžete upravovat i po naplánování.

POST/campaigns/{id}

Parametry v cestě

idstringpovinné
ID kampaně (cmp_…), nebo název kampaně.

Parametry v těle požadavku

namestring
Interní název kampaně.
subjectstring
Předmět. Podporuje slučovací značky.
from_emailstring
Adresa odesílatele na ověřené odesílací doméně.
from_namestring
Zobrazované jméno odesílatele.
reply_tostring
Adresa pro odpověď. Prázdný řetězec znamená, že odpovědi chodí na from_email.
preview_textstring
Text náhledu, který schránky zobrazují za předmětem. Při odeslání kampaně ho Emailit přidá jako skrytý text na začátek těla v HTML. Viz Vytvoření kampaně.
contentstring
Zdroj těla z editoru, uložený beze změny. Když změníte content nebo content_type a formát je html nebo text, Emailit odešle content jako nové tělo v HTML nebo v prostém textu.
content_typestring
Formát content: html, text nebo mjml. Pro tým Emailitu Emailit zkompiluje obsah mjml do html (alfaverze). Pro všechny ostatní je mjml jen označení.
utm_trackingboolean
Při odeslání přidá k odkazům kampaně UTM parametry. Viz Vytvoření kampaně.
utm_paramsobject | null
Hodnoty UTM: source, medium, campaign, content, term a id. Nahradí uložený objekt; null obnoví výchozí hodnoty. Viz Vytvoření kampaně.
smart_sending_hoursinteger | null
Vynechá kontakty, kterým jiná kampaň poslala e-mail za posledních tolik hodin, od 1 do 168. null ho vypne.
exclude_unengagedboolean
Vynechá kontakty, kterým byly za posledních 90 dní odeslány 3 nebo více e-mailů z kampaní a žádný z nich neotevřely ani v něm neklikly.
tagsstring[]
Až 20 štítků, každý nejvýše 50 znaků. Nahradí stávající štítky.
send_strategystring
immediate, throttled, local_time nebo smart_time. Použije se, když kampaň odešlete bez strategie.
send_optionsobject | null
Možnosti strategie send_strategy, úplně zkontrolované až při odeslání kampaně. Viz Odeslání nebo naplánování kampaně.
ab_testobject | null

A/B test s poli popsanými na stránce Vytvoření kampaně. Odesláním ab_test se test i jeho verze nahradí. Pokud chcete zachovat ID verze, a s ním i výsledky verze, uveďte ve verzi její id (cvr_…). null nebo "enabled": false test vypne a verze smaže.

recipientsobject[]

Seznamy kontaktů a segmenty, na které má kampaň cílit, nejvýše 100 položek. Nahradí stávající výčet. Zahrňte alespoň jednu položku s exclude nastaveným na false. Každá položka má buď audience_id, nebo segment_id, ne obojí:

  • audience_id (string): ID seznamu kontaktů (aud_…) v tomto workspace.
  • segment_id (string): ID segmentu (seg_…) v tomto workspace. Segmenty jsou v alfaverzi: přidat segment může jen tým Emailitu a ostatní požadavky vracejí 403 s error: "segments_alpha". Segmenty, které už kampaň má, lze ponechat.
  • exclude (boolean, výchozí hodnota false): true vynechá odběratele seznamu nebo kontakty segmentu, i když jsou také v některé zahrnuté položce.

Duplicitní položky se ignorují. Při odeslání Emailit pošle e-mail jednou každému kontaktu, který je přihlášený k zahrnutému seznamu nebo odpovídá zahrnutému segmentu, není ve vyloučeném seznamu ani segmentu, není globálně odhlášený, je přihlášený alespoň k jednomu seznamu a jeho adresa není zablokovaná. Segmenty se vyhodnotí v čase odeslání. Pokud do té doby vyloučený seznam kontaktů nebo segment přestane existovat, kampaň se neodešle.

Tělo v HTML a prostém textu se nastavuje při vytvoření kampaně. Neznámá pole v těle požadavku se ignorují.

Odpověď

Vrací upravený objekt kampaně včetně recipients a ab_test. Viz Načtení kampaně.

Pokud recipients neobsahuje žádný zahrnutý seznam kontaktů ani segment, má více než 100 položek, obsahuje položku s oběma ID nebo odkazuje na seznam či segment mimo workspace, vrací 422. 422 vrací také, když je některé nastavení nebo A/B test neplatný nebo když posíláte ab_test u kampaně, která není koncept ani naplánovaná, a pokud kampaň neexistuje, vrací 404.

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 }
  ]
}

Výpis kampaní

Vrací kampaně workspace od nejnovějších. Vyžaduje API klíč s oprávněním full.

GET/campaigns

Parametry dotazu

pageintegervýchozí: 1
Číslo stránky, začíná na 1.
limitintegervýchozí: 10
Počet kampaní na stránce, od 1 do 100.
statusstring
Zkrácený filtr podle stavu: draft, scheduled, sending (zahrnuje i queued), sent, canceled, archived nebo all.
matchstring

Hodnota all (výchozí) vyžaduje shodu se všemi filtry. S hodnotou or stačí shoda s kterýmkoli filtrem. Viz Filtrování.

orderstring

Klíč řazení pro tento výpis. Viz klíče řazení níže.

directionstring

asc, nebo desc.

Klíče filtrů

Filtry používají parametry dotazu ve tvaru key.condition=value, například status.exact=sent nebo created_at.after=2026-09-01. Podmínky pro jednotlivé typy najdete na stránce Filtrování a řazení.

Klíč Typ Poznámky
name string
subject string
status enum draft, scheduled, queued, sending, sent, archived
created_at date
sent_at date

Klíče řazení pro order: name, subject, status, created_at, sent_at.

Odpověď

Vrací stránku objektů kampaní bez reply_to, preview_text, content_type a recipients a z možností odesílání jen s tags, send_strategy a send_completes_at. Zbytek získáte endpointem Načtení kampaně.

dataobject[]
Kampaně na této stránce.
total_recordsinteger
Počet kampaní, které odpovídají dotazu.
next_page_urlstring | null
Cesta k další stránce, nebo null na poslední stránce. Obsahuje jen page a limit, takže když ji použijete, přidejte znovu vyhledávání a filtry.
previous_page_urlstring | null
Cesta k předchozí stránce, nebo null na první stránce.
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
}

Odeslání nebo naplánování kampaně

Odešle kampaň hned, nebo ji naplánuje, když předáte budoucí scheduled_at. Vyžaduje API klíč s oprávněním full a ověřený workspace: neověřené workspace nemohou kampaně odesílat a dostanou 403. Odeslat lze jen koncepty a naplánované kampaně: kampaň, která se odesílá nebo byla odeslána, vrací 422, takže opakovaný požadavek znovu neobešle všechny příjemce.

Před odesláním se ujistěte, že kampaň má from_email na ověřené doméně, předmět, tělo html nebo text a alespoň jeden zahrnutý seznam kontaktů nebo segment (nastavíte je endpointem Úprava kampaně). Každý e-mail stojí 2 kredity.

POST/campaigns/{id}/send

Parametry v cestě

idstringpovinné
ID kampaně (cmp_…), nebo název kampaně.

Parametry v těle požadavku

scheduled_atstring

Kdy odeslat. Přijímá ISO 8601 (2026-10-08T09:00:00Z), unixové časové razítko v sekundách nebo přirozený jazyk, například tomorrow at 9am (vyhodnocuje se v UTC). Čas musí být v budoucnosti a kampaň musí být ve stavu draft.

Pokud chcete odeslat hned, parametr vynechte. Pokud chcete naplánovanou kampaň odeslat dřív, zavolejte tento endpoint bez scheduled_at.

send_strategystring

Jak se odeslání rozloží v čase. Výchozí hodnota je strategie uložená u kampaně, jinak immediate. Strategie a její možnosti se u kampaně uloží. Viz Možnosti odesílání.

  • immediate: všem najednou, hned, nebo v čase scheduled_at.
  • throttled: rovnoměrným tempem per_hour e-mailů za hodinu, se začátkem hned, nebo v čase scheduled_at.
  • local_time: v zadaný čas v časovém pásmu každého kontaktu. scheduled_at se ignoruje.
  • smart_time: každému kontaktu v hodinu, kdy obvykle otevírá nebo kliká, v rámci okna od začátku.

Kampaně s A/B testem se odesílají jen se strategií immediate.

send_optionsobject

Možnosti strategie. Výchozí hodnota jsou možnosti uložené u kampaně.

  • throttled: per_hour (integer, povinné), od 100 do 1 000 000 e-mailů za hodinu.
  • local_time: local_time (string, povinné), čas ve tvaru YYYY-MM-DDTHH:mm, například 2026-10-08T09:00, a timezone (string, výchozí hodnota UTC), časové pásmo IANA pro kontakty, jejichž časové pásmo není známé. Časová pásma kontaktů pocházejí z měřicího skriptu. Odesílání začne, když zadaný čas nastane v nejranějším časovém pásmu (UTC+14); kontakty v pásmech, kde už uplynul, dostanou e-mail hned. Do té doby je kampaň ve stavu scheduled, takže musí jít o koncept. Pokud čas už uplynul ve všech časových pásmech, vrací 422.
  • smart_time: window_hours (integer, výchozí hodnota 24), od 1 do 48. Každý kontakt dostane e-mail v hodinu dne (UTC), ve které za posledních 90 dní nejčastěji otevíral nebo klikal, přičemž proklik se počítá třikrát víc než otevření, pokud tato hodina nastane v rámci okna. Kontakty bez této historie dostanou hodinu, která je nejčastější u ostatních příjemců. Kontakty bez obojího, nebo ty, jejichž hodina padne mimo okno, dostanou e-mail na začátku.

timezone se přijímá u každé strategie a musí to být platné časové pásmo IANA, používá ho ale jen local_time.

Odpověď

Odeslání hned: stav se změní na sending a Emailit vyvolá campaign.sending. Emailit potom určí příjemce: každý přihlášený kontakt ze zahrnutých seznamů kontaktů a každý kontakt, který odpovídá zahrnutým segmentům, každou adresu jednou, bez kontaktů z vyloučených seznamů nebo segmentů, bez kontaktů, které jsou globálně odhlášené nebo nejsou v žádném seznamu, a bez blokovaných adres. Segmenty se vyhodnotí v tuto chvíli. Vynechá také kontakty vyřazené pravidly smart_sending_hours a exclude_unengaged. E-maily se vytvoří v časech, které určí strategie odesílání. Jakmile jsou všichni příjemci předáni k odeslání, stav se změní na sent a Emailit vyvolá campaign.sent. Odeslání rozložené v čase zůstává ve stavu sending, dokud nenastane čas jeho poslední dávky (send_completes_at). send_summary kampaně ukazuje, kolika kontaktům byla kampaň odeslána a kolik jich bylo vynecháno. Doručování sledujte ve webovém rozhraní, endpointem Načtení statistik kampaně nebo pomocí událostí e-mailů.

A/B test: testovací skupina dostane verze a stav se změní na testing. Po uplynutí duration_hours dostane zbytek příjemců vítěznou verzi a stav se změní na sent.

Naplánování: stav se změní na scheduled a Emailit vyvolá campaign.scheduled. V naplánovaný čas kampaň přejde do stavu queued (campaign.queued) a potom se odešle stejně jako výše. Pokud se mezitím smazal vyloučený seznam kontaktů nebo segment, kampaň se místo odeslání vrátí do stavu draft.

Odpověď obsahuje object, id, name a nový status, při naplánování také scheduled_at.

Stavový kód Kdy
403 Workspace není ověřený, nebo API klíč nemá oprávnění full.
404 Parametru id neodpovídá žádná kampaň.
422 Kampaň není koncept ani naplánovaná (například se odesílá nebo byla odeslána), scheduled_at nelze zpracovat nebo není v budoucnosti, pokusili jste se naplánovat kampaň, která není koncept, kampaň nemá tělo html ani text, nemá žádné příjemce (nastavte je přes Úprava kampaně), vylučuje seznam kontaktů či segment, který už neexistuje, nebo jsou send_strategy a send_options neplatné. Chyba strategie uvádí název pole v 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"
}

Zrušení kampaně

Nastaví stav kampaně na canceled a vyvolá událost campaign.canceled. Vyžaduje API klíč s oprávněním full.

Zrušit lze jen kampaně ve stavu draft nebo sending; jakýkoli jiný stav vrací 422. Zrušení kampaně, která se odesílá, nestáhne zpět e-maily, které už jsou ve frontě k doručení.

POST/campaigns/{id}/cancel

Parametry v cestě

idstringpovinné
ID kampaně (cmp_…), nebo název kampaně.

Odpověď

Vrací object, id, name a status (canceled).

Pokud stav kampaně není draft ani sending, vrací 422, a pokud kampaň neexistuje, vrací 404.

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"
}

Načtení statistik kampaně

Načte report kampaně: kolik e-mailů bylo odesláno, doručeno, otevřeno a prokliknuto, výsledky podle poskytovatelů schránek, tržby z objednávek připsaných kampani (E-commerce, alfaverze) a u A/B testů výsledky jednotlivých verzí. Stejná čísla ukazuje report ve webovém rozhraní v sekci Email MarketingCampaigns. Vyžaduje API klíč s oprávněním full.

Každý počet je počtem e-mailů: e-mail otevřený třikrát se v opened počítá jednou. Procenta jsou vztažená k sent, pokud není uvedeno jinak, a mají dvě desetinná místa.

GET/campaigns/{id}/stats

Parametry v cestě

idstringPovinné

ID kampaně (cmp_...), nebo název kampaně. Názvy s mezerami nebo speciálními znaky zakódujte pro URL.

Parametry dotazu

fromstring

Počítá jen e-maily vytvořené v tento čas nebo později. Datum, nebo datum a čas ve formátu ISO 8601.

tostring

Počítá jen e-maily vytvořené v tento čas nebo dříve.

statusstring

Počítá jen e-maily, jejichž aktuální stav je tento: accepted, scheduled, delivered, loaded, clicked, attempted, bounced, failed, rejected, suppressed nebo complained. Jiné hodnoty se ignorují.

Filtry se vztahují na počty e-mailů, na poskytovatele a na počty A/B testu a from a to také na unsubscribed. Tržby, objednávky a kupující vždy zahrnují všechny objednávky připsané kampani a jejich míry vycházejí ze všech doručených e-mailů kampaně.

Odpověď

objectstring

Vždy campaign_stats.

campaign_idstring

ID kampaně (cmp_...).

sentinteger

Počet e-mailů vytvořených pro kampaň. sent_percent je 100, nebo 0, dokud se nic neodeslalo.

delivered, delivered_percentinteger, number

Počet e-mailů ve stavu delivered, loaded nebo clicked.

opened, opened_percentinteger, number

Počet e-mailů otevřených aspoň jednou.

clicked, clicked_percentinteger, number

Počet e-mailů s aspoň jedním změřeným proklikem.

click_through_percentnumber

clicked jako procento z opened.

bounced, suppressed, complained, attemptedinteger

Počet e-mailů ve stavu bounced, suppressed, complained nebo attempted (čekají na další pokus). Každé má také pole _percent.

not_processed, not_processed_percentinteger, number

Počet e-mailů, které jsou stále ve stavu accepted nebo scheduled.

unsubscribed, unsubscribed_percentinteger, number

Odhlášení z e-mailů kampaně.

providersobject[]

Výsledky podle poskytovatelů schránek příjemců, pro poskytovatele s aspoň jedním e-mailem. key je gmail, outlook.com, live.com, hotmail.com, yahoo, icloud nebo other a label je jeho zobrazovaný název. Každý má sent, delivered, opened, clicked a bounced s jejich poli _percent. sent_percent je podíl poskytovatele na všech e-mailech; ostatní procenta jsou vztažená k sent daného poskytovatele.

commerceobject

Jen pro tým Emailitu, dokud je E-commerce v alfaverzi: ostatní požadavky toto pole nedostanou a jejich variants A/B testu vynechávají orders, revenue a revenue_per_recipient. Objednávky připsané kampani. Tržby jsou celková částka objednávky minus vrácené peníze a zrušené objednávky se nepočítají. Částky v různých měnách se nesčítají: hlavní měna je ta s nejvyššími tržbami.

  • currency (string nebo null): hlavní měna.

  • revenue (number): tržby v hlavní měně.

  • orders (integer): připsané objednávky ve všech měnách.

  • buyers (integer): různí kupující ve všech měnách. Kupující, který platil ve dvou měnách, se počítá jednou.

  • average_order_value (number): v hlavní měně.

  • conversion_percent (number): buyers jako procento z doručených e-mailů kampaně.

  • revenue_per_recipient (number): revenue vydělené počtem doručených e-mailů kampaně.

  • by_currency (object[]): currency, orders, revenue, buyers a average_order_value pro každou měnu, seřazené od nejvyšších tržeb.

ab_testobject

Jen u kampaní s A/B testem.

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

  • leader_variant_id (string nebo null): verze, která má zatím nejlepší míru: otevření, prokliky nebo objednávky na odeslaný e-mail, nebo tržby na odeslaný e-mail.

  • win_probability (number nebo null): pravděpodobnost v procentech, že vedoucí verze skutečně překonává druhou v pořadí.

  • significance (string): significant (90 % nebo více, s aspoň 50 e-maily na verzi), promising (75 % nebo více, se stejným minimem), not_significant (pod 75 % s aspoň 1 800 e-maily na verzi) nebo inconclusive. U revenue vychází pravděpodobnost z objednávek.

  • variants (object[]): pro každou verzi variant_id, name, subject, is_winner, sent, delivered, opened, opened_percent, clicked, clicked_percent, orders, revenue a revenue_per_recipient. Jakmile se vítěz odešle zbytku příjemců, počty vítězné verze tyto e-maily zahrnují.

Pokud parametru id neodpovídá žádná kampaň, vrací 404, a pokud úložiště analytiky není dostupné, vrací 503.

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
      }
    ]
  }
}

Smazání kampaně

Trvale smaže kampaň. Vyžaduje API klíč s oprávněním full. Vyvolá událost campaign.deleted.

Smazání kampaně nemá vliv na e-maily, které už byly odeslány nebo zařazeny do fronty. Pokud chcete zastavit kampaň, která se odesílá, nejdřív ji zrušte.

DELETE/campaigns/{id}

Parametry v cestě

idstringpovinné
ID kampaně (cmp_…), nebo název kampaně.

Odpověď

Vrací object, id, name a deleted: true. Pokud kampaň neexistuje, vrací 404.

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
}

Byla tato stránka užitečná?

Děkujeme za zpětnou vazbu.

Děkujeme, čteme každou zprávu.

Esc

Oblíbené

↑↓procházet↵otevřítEsczavřít