{"openapi":"3.1.0","info":{"title":"eGate Mailing API","version":"1.0.0","description":"API pro systémy zákazníků eGate Mailing: kontakty a skupiny, odhlášení, odhlášené a vyřazené adresy, šablony.\n\nPřihlášení klíčem v hlavičce `Authorization: Bearer nwl_…` (klíč založíte v administraci: Systém → API). Limit 120 požadavků za minutu na klíč (hlavičky X-RateLimit-*). Časy ISO 8601 se zónou. Chyby: `{\"error\": {\"code\", \"message\", \"details\"?}}`.\n\nDokumentace s příklady a webhooky: https://www.egate.cz/emailove-kampane-api/","contact":{"name":"eGate","url":"https://www.egate.cz/emailove-kampane-api/"}},"servers":[{"url":"https://nwl.egate.cz/api/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"Účet","description":"Ověření klíče."},{"name":"Kontakty","description":"Přidávání kontaktů do skupin, odhlášení a stav adresy."},{"name":"Odhlášené adresy","description":"Odhlášené a vyřazené adresy pro synchronizaci do vašeho systému."},{"name":"Šablony","description":"Šablony e-mailů, např. HTML z externího editoru."}],"paths":{"/me":{"get":{"tags":["Účet"],"summary":"Ověření klíče","operationId":"me","responses":{"200":{"description":"Klíč platí.","content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"type":"string"},"demo":{"type":"boolean"}}}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/groups":{"get":{"tags":["Kontakty"],"summary":"Seznam skupin","operationId":"listGroups","responses":{"200":{"description":"Skupiny (ID použijte v poli groups).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}}}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"post":{"tags":["Kontakty"],"summary":"Přidání kontaktů (jeden nebo dávka do 1 000)","operationId":"createContacts","description":"Nové adresy se založí jako přihlášené. Existující adresy se nemění a odhlášené ani vyřazené se znovu nepřihlásí – jen se přidají do zadaných skupin. Neplatné adresy jsou v `errors`, ostatní se uloží. Neznámé ID skupiny = 422 celého požadavku.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ContactInput"},{"type":"object","required":["contacts"],"properties":{"contacts":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/ContactInput"}},"groups":{"type":"array","items":{"type":"integer"},"description":"Skupiny pro všechny kontakty v dávce."}}}]}}}},"responses":{"200":{"description":"Zpracováno (i když jsou některé kontakty v errors).","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"created":{"type":"integer"},"existing":{"type":"integer"},"invalid":{"type":"integer"},"added_to_groups":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"email":{"type":"string"},"result":{"type":"string","enum":["created","existing"]},"status":{"$ref":"#/components/schemas/ContactStatus"}}}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ItemError"}}}}}}},"400":{"description":"Tělo není platný JSON objekt (`invalid_json`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Neplatný požadavek: `invalid_payload`, `batch_too_large`, `invalid_groups`, `unknown_group`, `invalid_contacts`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/unsubscribe":{"post":{"tags":["Kontakty"],"summary":"Odhlášení adres","operationId":"unsubscribeContacts","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"emails":{"type":"array","maxItems":1000,"items":{"type":"string","format":"email"}}}}}}},"responses":{"200":{"description":"Výsledek pro každou adresu.","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"unsubscribed":{"type":"integer"},"already_unsubscribed":{"type":"integer"},"not_found":{"type":"integer"},"invalid":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"email":{"type":"string"},"result":{"type":"string","enum":["unsubscribed","already_unsubscribed","not_found"]}}}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ItemError"}}}}}}},"400":{"description":"Tělo není platný JSON objekt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Chybí email/emails nebo jich je víc než 1 000.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{email}":{"get":{"tags":["Kontakty"],"summary":"Stav adresy","operationId":"getContact","parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string","format":"email"},"description":"E-mailová adresa (zakódovaná pro URL, @ = %40)."}],"responses":{"200":{"description":"Kontakt.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"404":{"description":"Adresa v databázi není (`contact_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/unsubscribes":{"get":{"tags":["Odhlášené adresy"],"summary":"Odhlášené a vyřazené adresy od daného okamžiku","operationId":"listUnsubscribes","description":"Odhlášení (odkaz v e-mailu, jedno kliknutí v Gmailu, stížnost na spam, ruční, API) a vyřazení nedoručitelných adres, vzestupně podle času. Uložte si `next_cursor` a příště se ptejte od něj – nic se neztratí ani nezdvojí.","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"První dotaz: od kdy (ISO 8601)."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Další dotazy: next_cursor z předchozí odpovědi."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":500}}],"responses":{"200":{"description":"Události.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","description":"Vrací se vždy, i bez nových událostí."}}}}}},"422":{"description":"Chybí since i cursor, nebo jsou neplatné (`missing_since`, `invalid_since`, `invalid_cursor`, `invalid_limit`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates":{"get":{"tags":["Šablony"],"summary":"Seznam šablon","operationId":"listTemplates","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Hledání v názvu, předmětu nebo ID."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Šablony, nejnovější první.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateSummary"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Šablony"],"summary":"Nová šablona (např. HTML z externího editoru)","operationId":"createTemplate","description":"Chybějící odesílatel, adresa pro odpovědi a UTM se převezmou z poslední šablony. Bez `text` se textová verze vygeneruje z HTML. Obrázky dejte do HTML jako úplné adresy https://. V ukázkovém účtu jen čtení (403 `demo_read_only`).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateInput"}}}},"responses":{"201":{"description":"Šablona založena.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateWriteResult"}}}},"403":{"description":"Ukázkový účet (`demo_read_only`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Neplatná šablona (`invalid_template`, details = pole a zpráva), `invalid_field`, `too_large`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{id}":{"get":{"tags":["Šablony"],"summary":"Šablona včetně HTML a textu","operationId":"getTemplate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Šablona.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Template"}}}}}},"404":{"description":"Šablona neexistuje (`template_not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Šablony"],"summary":"Úprava šablony (jen poslaná pole)","operationId":"updateTemplate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"description":"Upravit jde jen šablonu, kterou ještě nepoužila žádná rozesílka (jinak 409 – založte novou). Při změně HTML se text přegeneruje jen tehdy, když byl předtím vygenerovaný z HTML.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateInput"}}}},"responses":{"200":{"description":"Šablona uložena.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateWriteResult"}}}},"403":{"description":"Ukázkový účet (`demo_read_only`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Šablona neexistuje.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Šablonu používá rozesílka (`template_in_use`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Neplatná šablona.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chybí nebo neplatný API klíč (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Překročený limit požadavků (`rate_limited`), viz hlavička Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"odhlaseni":{"post":{"summary":"Webhook: odhlášené a vyřazené adresy","operationId":"webhookUnsubscribes","description":"Zhruba každou minutu na adresu nastavenou v administraci (Systém → API → Webhook). Hlavička `X-Egate-Signature: t={unix čas},v1={HMAC-SHA256}` – HMAC z „{t}.{tělo}“ tajným klíčem webhooku; požadavky starší než 5 minut odmítněte. Odpověď 2xx = doručeno; jinak opakování za 1, 2, 4 … minuty (max. 6 h), po ~5 dnech chyb se webhook vypne. Stejná událost může přijít víckrát – zpracování má být opakovatelné. Přesměrování se nesleduje.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"ID doručení (i v hlavičce X-Egate-Delivery)."},"type":{"type":"string","enum":["events","test"]},"created_at":{"type":"string","format":"date-time"},"events":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Event"}}}}}}},"responses":{"200":{"description":"Přijato (jakákoli odpověď 2xx)."}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API klíč nwl_… z administrace."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"description":"Podrobnosti chyby (např. pole šablony nebo neplatné kontakty)."}}}}},"ItemError":{"type":"object","properties":{"index":{"type":"integer","description":"Pořadí položky v požadavku (od 0)."},"email":{"type":["string","null"]},"code":{"type":"string","enum":["invalid_email","too_long","duplicate","invalid_contact","invalid_field","invalid_groups"]},"message":{"type":"string"}}},"Group":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}},"ContactStatus":{"type":"string","enum":["active","unsubscribed","bounced"]},"ContactInput":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":128},"first_name":{"type":"string","maxLength":128},"last_name":{"type":"string","maxLength":128},"note":{"type":"string","maxLength":128},"groups":{"type":"array","items":{"type":"integer"},"description":"ID skupin z GET /groups."}}},"Contact":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"note":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/ContactStatus"},"groups":{"type":"array","items":{"type":"integer"}},"created_at":{"type":["string","null"],"format":"date-time"},"unsubscribed_at":{"type":["string","null"],"format":"date-time"},"bounced_at":{"type":["string","null"],"format":"date-time"}}},"Event":{"type":"object","properties":{"type":{"type":"string","enum":["unsubscribed","bounced"]},"email":{"type":"string"},"reason":{"type":"string","enum":["unsubscribed","complaint","mailbox_not_found","domain_not_found","repeated_failure","undeliverable"],"description":"unsubscribed/complaint u odhlášení, ostatní u vyřazení."},"occurred_at":{"type":"string","format":"date-time"}}},"TemplateInput":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"description":"Interní název (příjemce ho nevidí)."},"subject":{"type":"string","maxLength":255},"html":{"type":"string","description":"Max. 1 MB. Musí obsahovat odkaz [unsubscribe_url]."},"text":{"type":"string","description":"Textová verze; bez ní se vygeneruje z HTML."},"from_email":{"type":"string","format":"email"},"from_name":{"type":"string","maxLength":64},"reply_to":{"type":"string","format":"email"},"utm_params":{"type":"string","description":"Např. utm_source=newsletter&utm_medium=email – doplní se do odkazů."}}},"TemplateSummary":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subject":{"type":"string"},"created_at":{"type":["string","null"],"format":"date-time"},"used_in_sends":{"type":"integer"}}},"Template":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"subject":{"type":"string"},"from_email":{"type":"string"},"from_name":{"type":["string","null"]},"reply_to":{"type":["string","null"]},"utm_params":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"used_in_sends":{"type":"integer"},"web_url":{"type":"string","format":"uri"},"html":{"type":"string","description":"Jen v GET /templates/{id}."},"text":{"type":"string","description":"Jen v GET /templates/{id}."}}},"TemplateWriteResult":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Template"},"text_generated":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["missing_unsubscribe","relative_images","insecure_links","large_html","missing_text"]},"message":{"type":"string"}}}}}}}}}