Odeslání e-mailu

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.

Než začnete

• Ověřená odesílací doména ve vašem workspace. Viz Přidání odesílací domény.
• API klíč s oprávněním Full Access, nebo Sending Only. Viz API klíče.
• Produkční přístup, pokud odesíláte komukoli jinému než členům workspace. Viz Produkční přístup.
• Dost kreditů pro všechny příjemce (1 kredit za každého).

Odešlete základní e-mail

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

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.',
});

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.",
})

$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í, 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.

{
  "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. Příjemce s blokací typu recipient se přijme, ale místo doručení dostane stav suppressed.

Napište obsah

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, 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.

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

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',
  },
});

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",
    },
})

$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ů.

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.

Jak přiložit soubory, naplánovat odeslání nebo zajistit bezpečné opakování požadavků, najdete na stránkách Přílohy, Plánování a Idempotence.

Přečtěte si odpověď

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

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.

Události

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

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

Význam jednotlivých stavů najdete na stránce Stavy e-mailů.

Chyby

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

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

Zablokovaný workspace dostane při každém odeslání 403 s Workspace is suspended. Obecný formát chyb najdete na stránce Chyby.

Související

• Odeslání e-mailu v referenci API
• Šablony
• Stavy e-mailů
• Typy událostí webhooků
• Proč můj e-mail nedorazil?