Plánování a rušení e-mailů

Tato stránka vysvětluje, jak přes e-mailové API naplánovat e-mail na později, jak ho přesunout na jiný čas a jak e-mail zrušit, než odejde. Zrušení funguje i u e-mailů, které naplánované nebyly, pokud ještě nebyly doručeny.

Naplánujte e-mail

Přidejte scheduled_at do požadavku na odeslání. Odpověď obsahuje "status": "scheduled" a normalizovaný čas v scheduled_at a e-mail každého příjemce vyvolá místo email.accepted událost email.scheduled.

scheduled_at přijímá tyto formáty:

Čas, který je teď nebo v minulosti, odešle e-mail okamžitě se stavem accepted.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <reminders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "See you at 14:00.",
    "scheduled_at": "2026-10-05T09:00:00Z"
  }'

const email = await emailit.emails.send({
  from: 'Acme <reminders@acme.com>',
  to: 'ada@example.com',
  subject: 'Your appointment is tomorrow',
  text: 'See you at 14:00.',
  scheduled_at: '2026-10-05T09:00:00Z',
});

email = client.emails.send({
    "from": "Acme <reminders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "See you at 14:00.",
    "scheduled_at": "2026-10-05T09:00:00Z",
})

$email = $emailit->emails()->send([
    'from' => 'Acme <reminders@acme.com>',
    'to' => 'ada@example.com',
    'subject' => 'Your appointment is tomorrow',
    'text' => 'See you at 14:00.',
    'scheduled_at' => '2026-10-05T09:00:00Z',
]);

Emailit naplánovaný e-mail připraví už při požadavku, ne v čase odeslání. Šablona se vykreslí, přílohy z URL se stáhnou a kredity se strhnou předem. Pokud chcete změnit obsah, e-mail zrušte a odešlete nový.

Změňte čas odeslání

Použijte Úpravu naplánovaného e-mailu (POST /emails/{id}) s novým scheduled_at. Přijímají se stejné formáty.

• E-mail musí být ve stavu scheduled.
• Do jeho aktuálního času odeslání musí zbývat víc než 3 minuty.
• Nový čas odeslání musí být víc než 3 minuty v budoucnosti.

curl https://api.emailit.com/v2/emails/em_33VtK8mRq1xZp7LwN4cY2bHsDfa \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-10-05T15:00:00Z" }'

await emailit.emails.update('em_33VtK8mRq1xZp7LwN4cY2bHsDfa', {
  scheduled_at: '2026-10-05T15:00:00Z',
});

client.emails.update("em_33VtK8mRq1xZp7LwN4cY2bHsDfa", {
    "scheduled_at": "2026-10-05T15:00:00Z",
})

$emailit->emails()->update('em_33VtK8mRq1xZp7LwN4cY2bHsDfa', [
    'scheduled_at' => '2026-10-05T15:00:00Z',
]);

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "status": "scheduled",
  "scheduled_at": "2026-10-05T15:00:00.000Z",
  "updated_at": "2026-10-01T10:02:44.193027Z",
  "message": "Email schedule has been updated successfully"
}

Na rozdíl od nového odeslání se tady nečitelný čas odmítne s 422 Invalid scheduled_at. Požadavek, který porušuje pravidlo 3 minut nebo míří na e-mail, který není naplánovaný, selže s 422 Cannot update email. Požadavek s několika příjemci vytvoří jeden e-mail pro každého příjemce, takže přeplánujte každé ID em_ z mapy ids. Přeplánování ve webovém rozhraní dostupné není.

Zrušte e-mail

Odchozí e-mail můžete zrušit, dokud je v jednom z těchto stavů:

curl -X POST https://api.emailit.com/v2/emails/em_33VtK8mRq1xZp7LwN4cY2bHsDfa/cancel \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "status": "canceled",
  "in_flight": false,
  "message": "Email has been canceled and removed from the send queue."
}

Když je in_flight true, e-mail byl zrušen, ale pokus o doručení už možná probíhá, a zpráva zní „The current delivery attempt may still complete; remaining retries were stopped.“ Stav, který nelze zrušit, nebo naplánovaný e-mail, kterému do času odeslání zbývají méně než 3 minuty, vrátí 422 Cannot cancel email.

Zrušení nevrací kredity účtované při odeslání e-mailu přes API.

Jak zrušení funguje

Zrušení vyjme e-mail z odesílací fronty. Nejde o stažení zprávy ze schránky příjemce.

1. Emailit zkontroluje, že e-mail lze ještě zrušit.
2. Nastaví stav na canceled, přidá do historie doručení e-mailu záznam „Canceled“ a odebere e-mail z odesílací fronty.
3. Pokud už e-mail převzal doručovací proces, zkontroluje stav znovu těsně před předáním zprávy serveru příjemce, a když uvidí canceled, e-mail přeskočí.
4. Emailit vyvolá email.canceled s previous_status.

Pokud už zpráva byla na cestě k serveru příjemce, tento pokus ještě může uspět. Emailit ponechá stav canceled, i když se souběžný pokus doručí nebo se nedoručí, ale příjemce zprávu přesto může dostat. Berte zrušení jako „zastavit, než to odejde“, ne jako „vzít odeslání zpět“.

Stavy a události

Naplánovaný e-mail nevyvolá email.accepted, když nastane jeho čas odeslání. Úplný seznam najdete na stránce Stavy e-mailů.

Související

• Úprava naplánovaného e-mailu
• Zrušení e-mailu
• Odeslání e-mailu
• Stavy e-mailů
• Proč e-mail zůstal ve stavu Accepted nebo Scheduled?