Návod
API klíče
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.
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říkladsecret_••••••••. 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
403s"error": "Domain not authorized". - Přes SMTP se zpráva po
DATAodmítne s530 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íč
-
Otevřete API klíče. Otevřete Email APIAPI Keys a vyberte Add API key.
-
Pojmenujte klíč. Do pole Name zadejte název, ze kterého je poznat, kde se klíč používá, například
production-webnebowordpress-blog. Názvy musí být ve workspace jedinečné. -
Zvolte rozsah oprávnění. V poli Scope zvolte Full Access, Sending Only nebo Events Only.
-
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.
-
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.
Zavolejte Vytvoření API klíče s klíčem s plným přístupem. Výchozí hodnota scope je full; sending_domain_id platí jen pro klíče jen pro odesílání.
curl https://api.emailit.com/v2/api-keys \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "production-web",
"scope": "sending",
"sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
}'Pole key obsahuje jen odpověď 201:
{
"object": "api_key",
"id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
"name": "production-web",
"scope": "sending",
"sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
"last_used_at": null,
"created_at": "2026-10-01T09:30:00.000Z",
"updated_at": "2026-10-01T09:30:00.000Z",
"key": "secret_••••••••••••••••••••••••••••••••"
}Pokud je název už obsazený, vrací 409.
Použijte klíč
Klíč předávejte v hlavičce Authorization každého požadavku na API:
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.envpř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ě:
-
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. -
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íč.
-
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.
-
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. |