# Odeslání e-mailu

> Odesílání e-mailů přes POST /emails – pravidla pro odesílatele, příjemci, obsah, šablony, měření, odpověď, události webhooků a všechny chybové kódy.

Tento návod vysvětluje jednotlivé části požadavku `POST /emails` a co s nimi Emailit udělá, od adresy odesílatele až po chyby, které můžete dostat zpět. Úplný přehled parametrů najdete v referenci API na stránce [Odeslání e-mailu](/cs/docs/api-reference/emails/send/).

## Než začnete

- Ověřená odesílací doména ve vašem workspace. Viz [Přidání odesílací domény](/cs/docs/domains/add-a-domain/).
- API klíč s oprávněním **Full Access**, nebo **Sending Only**. Viz [API klíče](/cs/docs/developers/api-keys/).
- Produkční přístup, pokud odesíláte komukoli jinému než členům workspace. Viz [Produkční přístup](/cs/docs/workspaces/production-access/).
- Dost kreditů pro všechny příjemce (1 kredit za každého).

## Odešlete základní e-mail

**cURL**

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'
```

**Node.js**

```javascript
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});
```

**Python**

```python
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})
```

**PHP**

```php
$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);
```

## Nastavte adresu odesílatele

Pole `from` je povinné a přijímá jednu adresu v jednom z těchto tvarů:

- `billing@acme.com`
- `Acme Billing <billing@acme.com>`, nebo s uvozovkami `"Acme, Inc." <billing@acme.com>`

Doména za `@` musí být ověřená odesílací doména ve stejném workspace:

- **Shoda musí být přesná.** Na velikosti písmen v doméně nezáleží, ale `mail.acme.com` a `acme.com` jsou různé domény. Přidejte a ověřte každou subdoménu, ze které odesíláte.
- **Část adresy před zavináčem může být libovolná.** Pro `billing@` nebo `no-reply@` nepotřebujete schránku.
- **Domény čekající na kontrolu nemohou odesílat.** Doména, která ještě čeká na ruční kontrolu (**Pending verification**), se považuje za neověřenou.
- **Omezené klíče zůstávají u své domény.** Klíč s oprávněním **Sending Only** omezený na jednu doménu může odesílat jen z této domény.
- **Pozastavené domény jsou blokované.** Pokud doménu pozastavila [kondice odesílání](/cs/docs/deliverability/sending-health/), odeslání z ní se odmítají, dokud se pozastavení nezruší.

## Přidejte příjemce

Pole `to` je povinné, `cc` a `bcc` jsou volitelná. Každé z nich přijímá řetězec nebo pole řetězců, se zobrazovanými jmény i bez nich, a pojme až 50 adres. Řetězec může obsahovat několik adres oddělených čárkou; pokud zobrazované jméno samo obsahuje čárku, použijte pole.

Emailit odstraní duplicity napříč `to`, `cc` a `bcc` (bez ohledu na velikost písmen) a pak vytvoří **jeden e-mail pro každého jedinečného příjemce**, každý s vlastním ID `em_`. Každá kopie nese stejné hlavičky `To` a `Cc`, takže příjemci vidí konverzaci jako obvykle, a příjemci ve skryté kopii (`Bcc`) se v hlavičkách žádné kopie nikdy neobjeví.

Pokud má požadavek víc než jednoho příjemce, odpověď obsahuje mapu `ids` z adresy příjemce na ID e-mailu. `id` je e-mail prvního příjemce.

```json
{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}
```

Každý příjemce stojí 1 kredit a započítává se do vašich [limitů rychlosti](/cs/docs/api-reference/rate-limits/). Příjemce s [blokací](/cs/docs/suppressions/) typu `recipient` se přijme, ale místo doručení dostane stav `suppressed`.

## Napište obsah

| Pole | Pravidla |
| --- | --- |
| `subject` | Povinné, pokud ho neposkytne šablona. Znaky mimo ASCII se zakódují automaticky. |
| `html` | Tělo v HTML. Potřebujete `html`, `text`, nebo obojí, pokud je neposkytne šablona. |
| `text` | Tělo v prostém textu. Posílejte ho spolu s `html`: některé e-mailové klienty a spamové filtry dávají přednost zprávám s oběma verzemi. |
| `reply_to` | Řetězec nebo pole adres, na které mají chodit odpovědi. |

Pokud `reply_to` obsahuje stejnou adresu jako `from`, Emailit hlavičku `Reply-To` vynechá, protože nic nepřidává a některé spamové filtry ji penalizují.

## Odešlete e-mail se šablonou

Do pole `template` zadejte alias šablony nebo ID `tem_` a v `variables` předejte hodnoty pro proměnné [Temple](/cs/docs/templates/temple/), které šablona obsahuje.

- **Alias** odešle verzi, která je pro daný alias aktuálně publikovaná. Pokud žádná verze publikovaná není, požadavek selže s `404`.
- **ID `tem_`** odešle přesně tuto verzi, ať je publikovaná, nebo ne. Použijte ho k otestování konceptu před publikováním.

Pole v požadavku mají přednost před šablonou: `subject`, `html` nebo `text`, které odešlete, nahradí hodnotu ze šablony. Pokud neodešlete `reply_to`, použije se adresa pro odpověď ze šablony. Pole `from` musí být v požadavku vždy. Jak funguje publikování, najdete na stránce [Verze šablon](/cs/docs/templates/versions/).

**cURL**

```bash
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",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'
```

**Node.js**

```javascript
const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});
```

**Python**

```python
email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})
```

**PHP**

```php
$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);
```

`variables` funguje i bez šablony: Emailit vykreslí proměnné Temple v polích `subject`, `html` a `text`, která odešlete přímo v požadavku.

## Nastavte měření

Ve výchozím stavu se každý e-mail řídí nastavením **Track loads** a **Track clicks** své odesílací domény. U jednotlivých e-mailů ho přepíšete polem `tracking`:

- `"tracking": true` nebo `false` zapne, nebo vypne měření načtení (otevření) i prokliků zároveň.
- `"tracking": { "loads": true, "clicks": false }` nastaví každé zvlášť.

Měření funguje, jen když je CNAME záznam pro měření dané domény ověřený. Bez něj se e-mail odešle bez měření a požadavek přesto uspěje. Objekt `tracking` v odpovědi ukazuje nastavení, která se skutečně použila. Viz [Měření otevření a prokliků](/cs/docs/tracking/).

## Přidejte hlavičky a metadata

Pole `headers` slouží pro vlastní hlavičky e-mailu, například `List-Unsubscribe`, a `meta` pro vaše vlastní řetězcové dvojice klíč–hodnota. Emailit uloží `meta` spolu s e-mailem a přikládá je k událostem webhooků. Viz [Hlavičky a metadata](/cs/docs/email-api/headers-and-metadata/).

Jak přiložit soubory, naplánovat odeslání nebo zajistit bezpečné opakování požadavků, najdete na stránkách [Přílohy](/cs/docs/email-api/attachments/), [Plánování](/cs/docs/email-api/scheduling/) a [Idempotence](/cs/docs/email-api/idempotency/).

## Přečtěte si odpověď

Úspěšný požadavek vrací `200`:

| Pole | Popis |
| --- | --- |
| `object` | Vždy `email`. |
| `id` | ID `em_` e-mailu prvního příjemce. |
| `ids` | Mapa z adresy příjemce na ID e-mailu. Uvádí se, jen pokud je příjemců víc. |
| `token` | Interní token prvního e-mailu, používá se také v jeho Message-ID. |
| `message_id` | Hlavička `Message-ID` prvního e-mailu ve tvaru `<token@your-domain>`. |
| `from` | Adresa odesílatele tak, jak jste ji odeslali. |
| `to` | Adresy z `to` bez zobrazovaných jmen. |
| `cc`, `bcc` | Adresy z `cc` a `bcc`. Uvádějí se, jen pokud jste je odeslali. |
| `subject` | Výsledný předmět po vykreslení šablony. |
| `status` | `accepted`, nebo `scheduled`, pokud má e-mail čas odeslání v budoucnosti. |
| `scheduled_at` | Čas odeslání ve formátu ISO 8601, nebo `null`. |
| `created_at` | Kdy byl e-mail vytvořen. |
| `tracking` | Použité nastavení `loads` a `clicks`. |

Uložte si `id` (nebo mapu `ids`), abyste k e-mailu mohli přiřadit pozdější události webhooků a dohledat ho přes [Načtení e-mailu](/cs/docs/api-reference/emails/get/).

## Události

E-mail každého příjemce vyvolává vlastní události:

1. [`email.accepted`](/cs/docs/webhooks/events/email/accepted/) hned po požadavku, nebo [`email.scheduled`](/cs/docs/webhooks/events/email/scheduled/), pokud má čas odeslání v budoucnosti.
2. Události doručení, jak e-mail prochází zpracováním: [`email.delivered`](/cs/docs/webhooks/events/email/delivered/), [`email.attempted`](/cs/docs/webhooks/events/email/attempted/) (dočasná chyba, Emailit to zkusí znovu), [`email.bounced`](/cs/docs/webhooks/events/email/bounced/), [`email.failed`](/cs/docs/webhooks/events/email/failed/), [`email.rejected`](/cs/docs/webhooks/events/email/rejected/) nebo [`email.suppressed`](/cs/docs/webhooks/events/email/suppressed/). E-mail zadržený ke kontrole vyvolá `email.held`.
3. Události zapojení, pokud je zapnuté měření: [`email.loaded`](/cs/docs/webhooks/events/email/loaded/) a [`email.clicked`](/cs/docs/webhooks/events/email/clicked/). Nahlášení spamu vyvolá [`email.complained`](/cs/docs/webhooks/events/email/complained/).

Význam jednotlivých stavů najdete na stránce [Stavy e-mailů](/cs/docs/logs/email-statuses/).

## Chyby

Chyby validace vracejí seznam všech nalezených problémů:

```json
{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}
```

| Stav | `error` | Příčina | Řešení |
| --- | --- | --- | --- |
| `400` | `Validation failed` | Chybí povinné pole, adresa má chybný formát, pole obsahuje víc než 50 příjemců nebo je neplatná příloha. | Opravte každou položku v `validation_errors`. |
| `400` | `Invalid Idempotency-Key` | Hlavička `Idempotency-Key` má chybný formát. | Použijte 1–256 písmen, číslic, `-` nebo `_`. Viz [Idempotence](/cs/docs/email-api/idempotency/). |
| `401` | `Unauthorized` | API klíč chybí, nebo je neplatný. | Odešlete `Authorization: Bearer` s platným klíčem. |
| `402` | `Insufficient credits` | Workspace nemá na zaplacení všech příjemců. | [Kupte kredity](/cs/docs/billing/credits/), nebo zapněte [automatické dobíjení](/cs/docs/billing/auto-refill/). |
| `403` | `Workspace not verified` | Workspace je v režimu sandbox a některý příjemce není členem workspace. `code` je `unverified_workspace_recipient` a `blocked_recipients` obsahuje seznam adres. | [Požádejte o produkční přístup](/cs/docs/workspaces/production-access/), nebo testujte s adresami členů. |
| `403` | `Domain not authorized` | API klíč je omezený na jinou odesílací doménu. | Odesílejte z domény klíče, nebo použijte klíč bez omezení na doménu. |
| `403` | `Domain paused` | Kondice odesílání pozastavila doménu odesílatele. | Viz [Kondice odesílání](/cs/docs/deliverability/sending-health/). |
| `404` | `Template not found` | Alias nemá žádnou publikovanou verzi, nebo ID `tem_` v tomto workspace neexistuje. | Publikujte verzi, nebo zkontrolujte ID. |
| `409` | `Idempotency key in progress` | Jiný požadavek se stejným klíčem ještě probíhá. | Počkejte a pak požadavek zopakujte se stejným klíčem. |
| `413` | `Message too large` | Zakódovaná zpráva je větší než 40 MB. | Pošlete méně nebo menší přílohy, nebo na velké soubory odkažte. |
| `422` | `Domain not verified` | Doména odesílatele není v tomto workspace ověřenou odesílací doménou. | Ověřte doménu, nebo zkontrolujte, jestli nejde o subdoménu nebo překlep. |
| `422` | `Attachment error` | Přílohu z URL se nepodařilo stáhnout, nebo je větší než 25 MB. | Viz [Přílohy](/cs/docs/email-api/attachments/). |
| `429` | `Rate limit exceeded` nebo `Daily limit exceeded` | Překročili jste limit odesílání za sekundu nebo denní limit. | Počkejte počet sekund z `retry-after`, nebo požádejte o vyšší limit. |
| `503` | `Idempotency unavailable` | Úložiště idempotenčních klíčů není dostupné. | Zopakujte požadavek se stejným klíčem. |

Zablokovaný workspace dostane při každém odeslání `403` s `Workspace is suspended`. Obecný formát chyb najdete na stránce [Chyby](/cs/docs/api-reference/errors/).

## Související

- [Odeslání e-mailu](/cs/docs/api-reference/emails/send/) v referenci API
- [Šablony](/cs/docs/templates/)
- [Stavy e-mailů](/cs/docs/logs/email-statuses/)
- [Typy událostí webhooků](/cs/docs/webhooks/event-types/)
- [Proč můj e-mail nedorazil?](/cs/docs/kb/email-not-delivered-checklist/)

---
Zdroj: https://emailit.com/cs/docs/email-api/send-email/