Přejít na obsah
Dokumentace

Návod

Vytvářejte API klíče s plným přístupem, jen pro odesílání a jen pro události, omezte je na doménu, používejte je pro SMTP a vyměňujte je bez výpadku.

Aktualizováno 19. 10. 2026

API klíče autentizují vaše požadavky na REST API, připojení přes SMTP a relace na MCP serveru přihlášené API klíčem. Tato stránka vysvětluje tři rozsahy oprávnění klíčů, jak klíče vytvářet a spravovat a jak je bezpečně ukládat a vyměňovat.

Jak API klíče fungují

  • Každý klíč patří do jednoho workspace. Vše, co s ním uděláte, se odehraje v tomto workspace.
  • Nové klíče začínají na secret_ a za ním následuje 32 písmen a číslic, například secret_••••••••. Klíče vytvořené před zavedením této předpony fungují dál.
  • Emailit zobrazí celý klíč jen jednou, když ho vytvoříte nebo znovu vygenerujete. Hned si ho zkopírujte; znovu ho zobrazit nejde.
  • Klíč posíláte jako bearer token: Authorization: Bearer secret_…. U SMTP je klíč heslem.

Rozsahy oprávnění

Každý klíč má jeden ze tří rozsahů oprávnění. Rozsah zvolíte při vytváření klíče.

Full Access (full) Sending Only (sending) Events Only (events)
Odeslání e-mailu (POST /emails) Ano Ano Ne
Přeplánování, zrušení, opakované odeslání a přeposlání e-mailu Ano Ano Ne
SMTP relay Ano Ano Ne
Odesílání událostí workspace a vlastních událostí (POST /events, POST /events/batch) Ano Ne Ano
Odesílání produktů, objednávek a košíků (E-commerce, alfaverze) Ano Ne Ano
Čtení e-mailů (výpis, načtení, surový MIME, tělo, metadata, přílohy) Ano Ne Ne
Domény, šablony, kontakty, seznamy kontaktů, blokované adresy, webhooky, log událostí, kampaně, automatizace, ověřování a API klíče Ano Ne Ne
Nástroje MCP Všechny nástroje send-email, update-email, cancel-email, retry-email, forward-email a get-current-workspace send-event
Lze omezit na jednu odesílací doménu Ne Ano Ne

Klíč jen pro odesílání, který zavolá jakýkoli jiný endpoint, dostane 403 se zprávou jako Permission denied: read. Klíče s plným přístupem používejte pro interní úlohy, které spravují zdroje, a klíče jen pro odesílání pro vše, co potřebuje jen odesílat.

Klíče jen pro události jsou určené pro backendy, například e-shop, které jen zaznamenávají události workspace (w:) a vlastní události (c:). Nemohou nic zpětně číst, spravovat definice událostí ani odesílat e-maily a SMTP relay je odmítne. Jakékoli jiné volání dostane 403, například Permission denied: full.

Ve workspace s E-commerce (alfaverze pro tým Emailitu) mohou klíče jen pro události také vytvářet a upravovat produkty, objednávky a košíky (POST /products, /products/batch, /products/{id}, /orders, /orders/batch, /orders/{id} a /carts). Jejich odpovědi obsahují jen object, id a external_id.

Omezte klíč na jednu doménu

Při vytváření klíče jen pro odesílání můžete vybrat jednu ověřenou odesílací doménu. Klíč pak může odesílat jen z adres na této doméně:

  • Přes API vrátí odeslání z jiné domény 403 s "error": "Domain not authorized".
  • Přes SMTP se zpráva po DATA odmítne s 530 API key is restricted to sending domain: ….

Omezené klíče se hodí jako přístupové údaje pro jednotlivé aplikace nebo zákazníky a pro klíče, které musíte předat softwaru třetích stran, například pluginu CMS.

Než začnete

  • K vytváření, úpravám, novému vygenerování a mazání klíčů potřebujete ve workspace roli Admin. Členové s rolí Member seznam klíčů vidí, ale nemohou ho měnit. Viz Členové a role.
  • K odesílání s klíčem potřebujete alespoň jednu ověřenou odesílací doménu.

Vytvořte API klíč

  1. Otevřete API klíče. Otevřete Email APIAPI Keys a vyberte Add API key.

  2. Pojmenujte klíč. Do pole Name zadejte název, ze kterého je poznat, kde se klíč používá, například production-web nebo wordpress-blog. Názvy musí být ve workspace jedinečné.

  3. Zvolte rozsah oprávnění. V poli Scope zvolte Full Access, Sending Only nebo Events Only.

  4. Volitelně omezte doménu. U klíče jen pro odesílání vyberte v poli Domain odesílací doménu, nebo pole nechte prázdné a povolte všechny ověřené domény.

  5. Vytvořte a zkopírujte klíč. Vyberte Create. Zkopírujte klíč z dialogového okna a uložte ho do správce tajných údajů dřív, než okno zavřete. Emailit klíč zobrazí jen jednou.

Použijte klíč

Klíč předávejte v hlavičce Authorization každého požadavku na API:

Terminal
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'

Při odesílání přes SMTP použijte klíč jako heslo:

Nastavení Hodnota
Server smtp.emailit.com
Port 587 (STARTTLS, doporučeno), 465 (TLS), 2525 nebo 2587 (STARTTLS)
Uživatelské jméno emailit
Heslo Váš API klíč

Všechny možnosti najdete na stránce Nastavení SMTP.

Spravujte klíče

Když klíč otevřete v Email APIAPI Keys, uvidíte jeho rozsah oprávnění, doménu, datum Created, čas Last used a nastavení SMTP, které s ním máte použít.

Akce Co se stane API
Edit Přejmenuje klíč. Uloží se jen název; pokud chcete změnit rozsah oprávnění nebo omezení na doménu, vytvořte nový klíč a přejděte na něj. Úprava API klíče
Regenerate Vydá pro stejný klíč nový tajný údaj a jednou ho zobrazí. Starý tajný údaj okamžitě přestane fungovat. Klíč si ponechá ID, název, rozsah oprávnění i doménu a údaj Last used se vynuluje. Nové vygenerování API klíče
Delete Klíč okamžitě přestane fungovat a zmizí ze seznamu. Tuto akci nelze vrátit zpět. Smazání API klíče

Údaj Last used se aktualizuje pokaždé, když klíč autentizuje požadavek na API nebo přihlášení přes SMTP. U klíče, který ještě nikdy nebyl použit, se zobrazí Never. Endpointy API, které přijímají ID klíče, přijímají i jeho název.

Ukládejte klíče bezpečně

  • Uchovávejte klíče na serveru. Nikdy nevkládejte klíč do JavaScriptu v prohlížeči, mobilní aplikace, veřejného repozitáře ani tiketu pro podporu. Kdokoli s klíčem může odesílat e-maily vaším jménem a utrácet vaše kredity.
  • Používejte proměnné prostředí nebo správce tajných údajů. Klíč načítejte za běhu, například z EMAILIT_API_KEY. Soubory .env přidejte do .gitignore.
  • Dejte každé aplikaci a prostředí vlastní klíč. Díky samostatným klíčům pro produkci, staging a každý nástroj třetí strany snadno zjistíte, kdo co odeslal, a jeden klíč odvoláte, aniž byste museli sahat na ostatní.
  • Používejte co nejužší oprávnění. Pokud aplikace jen odesílá e-maily, dejte jí klíč jen pro odesílání, a kde to jde, omezený na její doménu. Pokud jen zaznamenává události, dejte jí klíč jen pro události.
  • Sledujte využití. Stránka Email APILogs uvádí požadavky přes API a SMTP pro jednotlivé klíče a e-maily v Email APIEmails můžete filtrovat podle API klíče. Viz Logy požadavků.
  • Při úniku jednejte rychle. Pokud klíč unikne, okamžitě ho znovu vygenerujte nebo smažte a pak v logech zkontrolujte nečekaná odeslání.

Vyměňte klíč bez výpadku

Nové vygenerování klíče starý tajný údaj okamžitě odstřihne, proto ho používejte jen tehdy, když je klíč kompromitovaný. Při plánované výměně nechte starý a nový klíč nějakou dobu fungovat souběžně:

  1. Vytvořte nový klíč. Přidejte klíč se stejným rozsahem oprávnění a omezením na doménu, jaké má klíč, který nahrazujete. Dejte mu název s datem, například production-web-2026-10.

  2. Nasaďte nový klíč. Aktualizujte tajný údaj ve správci tajných údajů nebo v prostředí a nasaďte ho na všechny servery, workery a plánované úlohy, které používají starý klíč.

  3. Ověřte přechod. Otevřete nový klíč a zkontrolujte, že je údaj Last used čerstvý. V Email APILogs vyfiltrujte starý klíč a zkontrolujte, že požadavky ustaly.

  4. Smažte starý klíč. Až se čas Last used u starého klíče přestane měnit, klíč smažte.

Řešení problémů

Příznak Příčina Řešení
401 Invalid API key Klíč byl smazán, znovu vygenerován nebo špatně opsán. Zkopírujte do konfigurace aktuální klíč včetně předpony secret_.
403 Permission denied: read nebo Permission denied: full Klíč jen pro odesílání nebo jen pro události zavolal endpoint mimo svůj rozsah oprávnění. Pro toto volání použijte klíč s plným přístupem.
403 Domain not authorized Klíč je omezený na jinou doménu, než je doména adresy from. Odesílejte z domény klíče, nebo použijte jiný klíč.
SMTP 535 Authentication failed Heslo není platný API klíč, nebo je to klíč jen pro události. Jako heslo použijte klíč s plným přístupem, nebo jen pro odesílání, a jako uživatelské jméno emailit.
Jak se požadavky autentizují.
Vytváření, výpis, úpravy, nové vygenerování a mazání klíčů.
Server, porty, TLS a přístupové údaje.
Jak Emailit chrání váš účet a data.

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

Děkujeme za zpětnou vazbu.

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