API klíče

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 dva 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 dvou rozsahů oprávnění. Rozsah zvolíte při vytváření klíče.

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.

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íč

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

{
  "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_••••••••••••••••••••••••••••••••"
}

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:

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

Spravujte klíče

Když klíč otevřete v Email API›API 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.

Ú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.
• Sledujte využití. Stránka Email API›Logs uvádí požadavky přes API a SMTP pro jednotlivé klíče a e-maily v Email API›Emails 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 API›Logs 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ů

Související