# Přehled pro vývojáře

> Základní URL, autentizace, ID objektů, chyby, stránkování, limity rychlosti, SDK, webhooky a MCP. Konvence, které sdílí každá integrace s Emailitem.

Tato stránka shrnuje konvence, které potřebujete znát, než začnete psát kód pro Emailit: kde API najdete, jak se požadavky autentizují, jak se identifikují objekty a jak fungují chyby, stránkování a limity rychlosti. Každá sekce odkazuje na podrobnou referenci.

## Způsoby integrace

| Rozhraní | Endpoint | K čemu slouží |
| --- | --- | --- |
| REST API | `https://api.emailit.com/v2` | Odesílání e-mailů a správa všech zdrojů z kódu. |
| SMTP relay | `smtp.emailit.com` | Aplikace, frameworky a CMS, které už umí SMTP. Viz [Nastavení SMTP](/cs/docs/smtp/settings/). |
| Webhooky | Váš HTTPS endpoint | Události doručení, zapojení a zdrojů v reálném čase. |
| MCP server | `https://api.emailit.com/mcp` | Práce AI asistentů, jako jsou Claude, ChatGPT a Cursor, s vaším workspace. |
| OAuth 2.1 | `https://api.emailit.com/oauth/*` | Integrace, které jednají jménem uživatelů Emailitu, aniž by pracovaly s jejich API klíči. |

Nevíte, jestli použít API, nebo SMTP? Přečtěte si stránku [Volba mezi API a SMTP](/cs/docs/get-started/api-or-smtp/).

## Základní URL a verzování

Všechny endpointy REST API mají jednu společnou základní URL:

```text
https://api.emailit.com/v2
```

`v2` je aktuální a jediná zdokumentovaná verze. Původní API `v1` je zastaralé; viz [Verzování](/cs/docs/api-reference/versioning/).

## Autentizace

API klíč posílejte jako bearer token v hlavičce `Authorization` každého požadavku:

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

- API klíče začínají na `secret_`. Starší klíče bez předpony fungují dál.
- Každý klíč patří do jednoho workspace a má rozsah oprávnění: **Full Access** (`full`) může volat všechny endpointy, **Sending Only** (`sending`) může jen odesílat a spravovat odeslané e-maily. Viz [API klíče](/cs/docs/developers/api-keys/).
- Ve stejné hlavičce se přijímají i přístupové tokeny OAuth vydané [OAuth aplikacím](/cs/docs/developers/oauth-apps/).
- Chybějící klíč vrací `401` s `API key required`, neznámý klíč vrací `401` s `Invalid API key` a zablokovaný workspace vrací `403` s `Workspace is suspended`.

Nikdy nevolejte API se svým klíčem z prohlížeče ani z mobilní aplikace. Klíč uchovávejte na serveru. Podrobnosti: [Autentizace](/cs/docs/api-reference/authentication/).

## ID a předpony

Každý objekt má textové ID s předponou typu, takže na první pohled poznáte, k čemu ID patří.

| Objekt | Předpona | Příklad |
| --- | --- | --- |
| E-mail | `em_` | `em_4K6oASS7KP9ztzWmSN9ndEu13HW` |
| Odesílací doména | `dom_` | `dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6` |
| API klíč | `key_` | `key_4F2kN8sQwE1rT6yU3iO9pA7sD5f` |
| Seznam kontaktů | `aud_` | `aud_3zR8tY2uI6oP4aS1dF9gH7jK5lM` |
| Odběratel | `sub_` | `sub_4K6oASS7KP9ztzWnqS4svxApJzO` |
| Kontakt | `con_` | `con_4A9sD2fG6hJ1kL8zX3cV7bN5mQw` |
| Šablona | `tem_` | `tem_3wE8rT1yU5iO9pA2sD6fG4hJ7kL` |
| Blokace | `sup_` | `sup_4K6oASS7KP9ztzWol5ElicOeKFE` |
| Webhook | `wh_` | `wh_3mN7bV2cX6zL9kJ4hG1fD8sA5pO` |
| Požadavek webhooku | `whr_` | `whr_4K6oASS7KP9ztzWpVUIec9Jneax` |
| Událost | `evt_` | `evt_4K6oASS7KP9ztzWpqId2iIptac5` |
| Kampaň | `cmp_` | `cmp_4B1nM5qW9eR3tY7uI2oP6aS8dF4` |
| Formulář | `frm_` | `frm_4C3vB7nM1qW5eR9tY2uI6oP8aS4` |
| Odpověď formuláře | `fsub_` | `fsub_4K6oASS7KP9ztzWqvxLV3IsFRs8` |
| Automatizace | `aut_` | `aut_4D5fG9hJ3kL7zX1cV6bN2mQ8wE4` |
| Spuštění automatizace | `aur_` | `aur_4K6oASS7KP9ztzWrWOjGgqompRo` |
| Ověření e-mailu | `ev_` | `ev_4E7gH1jK5lZ9xC3vB8nM2qW6eR4` |
| Seznam k ověření | `evl_` | `evl_4F9hJ3kL7zX1cV5bN9mQ2wE6rT8` |
| DMARC report | `dmr_` | `dmr_4K6oASS7KP9ztzWsW7e5qkOYHO6` |

Domény vytvořené před přechodem na ID `dom_` mohou mít ještě ID `sd_` nebo `sed_`.

Některé endpointy místo ID přijímají i čitelný identifikátor: název u API klíčů, domén, webhooků, kampaní a seznamů kontaktů a e-mailovou adresu u kontaktů a blokovaných adres. E-maily, šablony a události se dohledávají jen podle ID.

## Požadavky a odpovědi

- **JSON na vstupu i na výstupu.** Těla požadavků posílejte jako JSON s `Content-Type: application/json`. Chybný JSON vrací `400` s `Invalid JSON in request body`. Tělo požadavku může mít až 50 MB; výsledná zpráva MIME e-mailu může mít až 40 MB.
- **Chyby.** Většina chyb vrací `{"statusCode", "error", "message"}`. Chyby validace navíc obsahují pole `details` a chyby při odesílání vracejí `validation_errors`. Funkce vázané na tarif vracejí `403` s `"error": "plan_required"`. Viz [Chyby](/cs/docs/api-reference/errors/).
- **Stránkování.** Endpointy pro výpis přijímají `page` a `limit` (od 1 do 100) a vracejí `data`, `next_page_url` a `previous_page_url`. Šablony a automatizace používají `page` a `per_page`. Viz [Stránkování](/cs/docs/api-reference/pagination/).
- **Filtrování a řazení.** Filtrujte pomocí `field.condition=value`, filtry kombinujte s `match=all`, nebo `match=or` a řaďte pomocí `order` a `direction`. Například `GET /v2/emails?status.exact=bounced&order=created_at&direction=desc`. Viz [Filtrování a řazení](/cs/docs/api-reference/filtering/).
- **Idempotence.** Posílejte hlavičku `Idempotency-Key` u `POST /emails` a `POST /emails/:id/forward`, aby byla opakování požadavků bezpečná. Emailit po dobu 24 hodin vrací znovu první odpověď. Viz [Idempotence](/cs/docs/api-reference/idempotency/).
- **Limity rychlosti.** Odesílání je omezené pro každý workspace, ve výchozím stavu na 2 e-maily za sekundu a 5 000 e-mailů za den, společně pro API i SMTP. Odpovědi obsahují hlavičky `ratelimit-*` a odpověď `429` obsahuje `retry-after`. Viz [Limity rychlosti](/cs/docs/api-reference/rate-limits/) a [Limity a kvóty](/cs/docs/limits/).

## SDK

Oficiální knihovny obalují REST API pro Node.js, PHP, Laravel, Python, Ruby, Go, Javu, .NET a Rust. Všechny najdete na [GitHubu](https://github.com/emailit). Instalační příkazy najdete na stránce [SDK a knihovny](/cs/docs/sdks/) a kompletní příklady v návodech pro frameworky, počínaje [Node.js](/cs/docs/frameworks/nodejs/).

## Webhooky

Webhooky posílají události na váš endpoint, jakmile nastanou: doručení, nedoručení, otevření, prokliky, příchozí poštu a změny domén, kontaktů a dalších zdrojů. Každý požadavek obsahuje pole JSON až se 100 událostmi a je podepsaný pomocí HMAC-SHA256 v hlavičce `X-Emailit-Signature`. Neúspěšné požadavky se opakují, celkem až 11 pokusů. Začněte stránkami [Nastavení webhooku](/cs/docs/webhooks/set-up/) a [Ověření podpisu webhooků](/cs/docs/webhooks/request-signature/).

## MCP server a AI nástroje

Hostovaný [MCP server](/cs/docs/mcp/) na `https://api.emailit.com/mcp` dává AI asistentům 109 nástrojů pro celé API v2, od odesílání e-mailů po kampaně a automatizace. Asistenti se přihlašují přes OAuth nebo API klíčem a [pluginy Emailit](/cs/docs/mcp/plugins-and-skills/) přidávají dovednosti pro ChatGPT, Codex, Claude Code, Cursor a Grok.

Dokumentace je publikovaná i pro AI: každá stránka má verzi v Markdownu a [/docs/llms.txt](/cs/docs/developers/llms-txt/) obsahuje rejstřík všech stránek.

## Další kroky

  - [Vytvořte API klíč](/cs/docs/developers/api-keys/): Zvolte rozsah oprávnění, omezte klíč na doménu a bezpečně ho uložte.
  - [Odešlete první e-mail](/cs/docs/quickstart/api/): Proveďte první volání API za pár minut.
  - [SDK a knihovny](/cs/docs/sdks/): Oficiální knihovny pro devět jazyků a frameworků.
  - [Reference API](/cs/docs/api-reference/): Všechny endpointy, parametry a odpovědi.

---
Zdroj: https://emailit.com/cs/docs/developers/