Autentizace

Každý požadavek na API Emailitu musí v hlavičce Authorization nést přístupový údaj. Tato stránka popisuje dva druhy přístupových údajů (API klíče a přístupové tokeny OAuth), co které oprávnění umožňuje a všechny chyby autentizace, které můžete dostat.

API klíče

API klíč patří do jednoho workspace a každý požadavek, který s ním pošlete, pracuje s tímto workspace. Klíče vypadají takto:

secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG

Tedy secret_ a za ním 32 písmen a číslic. Klíče vytvořené před zavedením formátu secret_ předponu nemají a fungují dál.

Klíče vytvoříte ve webovém rozhraní v sekci Email API›API Keys, nebo přes endpoint Vytvoření API klíče. Tajný údaj se zobrazí jen jednou, když klíč vytvoříte nebo znovu vygenerujete, proto ho hned uložte. Jak klíče spravovat, popisuje stránka API klíče.

Stejné klíče fungují jako heslo pro SMTP u SMTP relay.

Posílejte klíč s každým požadavkem

V hlavičce Authorization použijte schéma Bearer. API nepřijímá klíče v řetězci dotazu ani v těle požadavku.

curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();

import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()

SDK tuto hlavičku nastaví za vás, když klientovi předáte klíč.

Rozsahy oprávnění

Každý klíč má jedno ze dvou oprávnění. Zvolíte ho při vytvoření klíče a později ho nelze změnit.

Klíč s oprávněním sending může volat tyto endpointy a nic jiného:

Čtení e-mailů (výpis, načtení, surový MIME, tělo, metadata, přílohy a stav) vyžaduje klíč s oprávněním full. Když klíč s oprávněním sending zavolá jakýkoli jiný endpoint, API vrátí 403 se zprávou Permission denied: full (u endpointů pro čtení e-mailů Permission denied: read).

Oprávnění každého endpointu uvádí stránka Všechny endpointy.

Omezte klíč na jednu doménu

Klíč s oprávněním sending lze také uzamknout na jednu odesílací doménu. Při vytvoření klíče předejte ID domény v poli sending_domain_id. Omezený klíč může odesílat jen z adres na této doméně. Jakákoli jiná doména v poli from vrátí 403:

{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}

Omezení na doménu platí jen pro klíče s oprávněním sending. Klíč s oprávněním full má vždy přístup ke všem doménám ve workspace.

Přístupové tokeny OAuth

Aplikace, které jednají jménem uživatele Emailitu, například MCP klienti a integrace třetích stran, o API klíč nežádají. Místo toho používají OAuth 2.1: uživatel se přihlásí do Emailitu, vybere workspace, které aplikace smí používat (všechny, nebo jen vybrané), a schválí oprávnění sending, nebo full. Aplikace pak dostane přístupový token. Uživatel může tento přístup změnit nebo odvolat na stránce Připojené aplikace.

Přístupové tokeny posílejte ve stejné hlavičce jako API klíče:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Přístupový token platí 15 minut a pracuje s výchozím workspace uděleného přístupu, s uděleným oprávněním a s rolí uživatele v tomto workspace. Aplikace ho obnovují obnovovacím tokenem. Jak takovou aplikaci vytvořit, popisuje stránka OAuth aplikace.

Chyby autentizace

Autentizace proběhne před vším ostatním, takže tyto chyby může vrátit kterýkoli endpoint.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}

{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}

Neověřené workspace

Nové workspace začínají jako neověřené. Dokud Emailit neschválí produkční přístup, API odesílá jen na e-mailové adresy účtů členů workspace. Odeslání, opakované odeslání nebo přeposlání komukoli jinému vrátí 403 s kódem unverified_workspace_recipient a seznamem blocked_recipients a kampaně nelze odeslat vůbec. Na všechno ostatní vaše API klíče fungují normálně.

Uchovejte klíče v tajnosti

API klíč dává přístup k vašemu workspace, takže s ním zacházejte jako s heslem.

• Volejte API jen ze svého serveru. Nikdy nedávejte klíč do JavaScriptu v prohlížeči, do mobilní aplikace ani do jiného kódu, který běží na cizím zařízení.
• Neukládejte klíče do správy verzí. Načítejte je z proměnných prostředí nebo ze správce tajných údajů.
• Pro každou aplikaci a prostředí vytvořte samostatný klíč a pojmenujte ho podle místa použití, abyste mohli jeden odvolat a ostatní nerozbít.
• Dejte každému klíči jen takový přístup, jaký potřebuje: pro většinu aplikací stačí klíč s oprávněním sending omezený na jednu doménu.
• Kontrolujte pole last_used_at ve výpisu API klíčů a mažte klíče, které už nepoužíváte.
• Pokud klíč unikne, hned ho vygenerujte znovu, nebo smažte. Starý tajný údaj okamžitě přestane fungovat.

Související