Požadavek send-email

Účel a dopady

Odešle jednu nebo více e-mailových zpráv prostřednictvím poštovního profilu (SMTP nastavení uloženého v x_mail_profile), volitelně uloží kopii odeslané zprávy do IMAP schránky. Vedlejší efekty: skutečné odeslání e-mailu přes SMTP, případně zápis zprávy do IMAP složky poštovního serveru.

Tato stránka popisuje jen chování platné pro send-email; drop-email je mimo rozsah této revize.

Dostupnost, kontext, oprávnění apod.

• Dostupné každému přihlášenému uživateli; přístup ke konkrétnímu mailovému profilu (profile) je dále omezen obecným mechanismem admin-filtrů podle efektivní role volajícího – ne pevnou rolí typu r_admin.
• Vyžaduje běžící mailovou službu serveru; je-li zastavená, požadavek vždy skončí chybou bez ohledu na oprávnění.
• Podléhá standardnímu transakčnímu zpracování obálky <request> (transactional/přeskočení při odvolané transakci) – viz obálka požadavku.

XML požadavek (syntax + popis)

  <request>
   <send-email
    profile="{number}"
    opt-roles="{string}"
    all-or-nothing="{bool}"
    verbose="{bool}"
    folder="{string}"
    flags="{string}"
    >
    <email ... /> *
   </send-email>
  </request>

Parametry a pravidla (atributy, potomci)

• profile - Profil odesílatele - Číselný identifikátor záznamu v x_mail_profile. Je-li vynechán nebo prázdný, použije se výchozí mailový profil přihlášeného uživatele (pokud jej má nastaven). (typ: number; nepovinný; výchozí: výchozí mailový profil volajícího)
• opt-roles - Volitelná role - Přepíše efektivní roli použitou při ověření přístupu k profilu oproti roli přihlášení. (typ: string; nepovinný)
• all-or-nothing - Přerušit při první chybě příjemce - Je-li jiné než "false" (tedy i bez uvedení), přeruší odesílání dané zprávy ostatním příjemcům, jakmile selže odeslání jednomu z nich; týká se jen dané jednotlivé zprávy, ne ostatních potomků email v témže požadavku. (typ: bool; nepovinný; výchozí: true)
• verbose - Detailní odpověď - Je-li "true", ke každému email v odpovědi (úspěšnému i neúspěšnému) se přidá výpis jednotlivých příjemců a jejich stavu. (typ: bool; nepovinný; výchozí: false)
• folder - Cílová IMAP složka - Je-li uvedena, server se po odeslání pokusí uložit kopii zprávy do této IMAP složky poštovní schránky profilu (např. /Sent Items); při vynechání se kopie neukládá. (typ: string; nepovinný)
• flags - IMAP příznaky uložené kopie - Použije se jen společně s folder; řetězec IMAP příznaků (např. \Seen) nastavených na uloženou kopii zprávy. Tento atribut dosavadní dokumentace vůbec nezmiňovala. (typ: string; nepovinný)

Potomek: email (0 a vícekrát) – jedna odesílaná zpráva. Přesná syntaxe obsahu uzlu email na vstupu (hlavičky, příjemci, tělo, přílohy, případné operace nad dokumenty) není v tomto rozsahu dokumentována; dosavadní odkaz na „asi:email“ neodpovídá žádné existující stránce dokumentace.

Závislosti

• flags má smysl jen společně s folder.
• all-or-nothing ovlivňuje jen odesílání v rámci jedné zprávy (email), ne zpracování ostatních email potomků v témže požadavku – ty se zpracují vždy všechny bez ohledu na výsledek předchozích.

Příklady požadavku

(Zatím bez ověřeného příkladu.)

Zpracování a vedlejší účinky

• Server nejprve ověří platnost profile (číselná hodnota nebo výchozí profil uživatele); nelze-li jej určit, vrátí chybu bez pokusu o odeslání.
• Poté ověří přístup k danému profilu pro efektivní roli (role/opt-roles); selže-li samotné vyhodnocení filtru (chyba databáze), vrátí chybu s vnořeným diagnostickým uzlem; zamítne-li filtr přístup, vrátí chybu oprávnění.
• Dále ověří, že mailová služba běží a že pro daný profile existuje aktivní synchronizační profil; jinak vrátí příslušnou chybu.
• Kořenový uzel odpovědi <send-email status="ok"> se zapíše hned na začátku zpracování jednotlivých zpráv a už se dál nemění – ani selhání jednotlivých email potomků nezmění send-email/@status zpět na "error". Celkový neúspěch je signalizován jen jednotlivými uzly <email status="error"> a interním příznakem výsledku požadavku (ovlivňujícím např. odvolání transakce), ne atributem send-email/@status.
• Pro každý potomek email (v pořadí, bez namespace) server: (1) zpracuje jeho XML obsah (parseMailFromXML) – při selhání vrátí <email status="error" detail="Zpracovani XML mailu se nezdarilo"> s vnořeným diagnostickým uzlem a pokračuje dalším email; (2) při úspěchu zprávu odešle (sendMail, respektuje all-or-nothing) – při selhání vrátí <email status="error" detail="Pri odesilani mailu doslo k chybe"> s vnořeným diagnostickým uzlem (a při verbose="true" i výpisem příjemců), jinak vrátí <email status="ok" .../> s msg-id/mkey a případně store, je-li uveden folder.
• Atribut dkey z requestového uzlu email (pokud je uveden) se echoem vrací zpět ve všech třech větvích (úspěch i obě chyby).
• Zpracování jednoho email NEPŘERUŠÍ zpracování dalších potomků email v témže požadavku (na rozdíl např. od sql-query) – server se pokusí odeslat všechny.

XML odpověď (syntax + popis)

  <response>
   <send-email
    status="ok|error"
    detail="{string}"
    >
    <email ... /> *
   </send-email>
  </response>

Parametry a pravidla (atributy, potomci) – odpověď

• status - Výsledek - "ok" u prvotních úspěšných kroků a vždy u kořenového uzlu, jakmile začalo zpracování jednotlivých zpráv (viz „Zpracování“ výše); "error" jen u chyb nastalých před zahájením tohoto zpracování (neplatný profil, chybějící oprávnění, zastavená služba, chyba admin-filtru). (typ: enum; povolené hodnoty: ok, error)
• detail - Popis chyby - Přítomen jen u chyb nastalých před zahájením zpracování zpráv. (typ: string; nepovinný)

Uzel email

  <email
   status="ok|error"
   msg-id="{string}"
   mkey="{number}"
   dkey="{string}"
   store="append|stored|failed"
   detail="{string}"
   >
   <recipient ... /> *
  </email>

• status - Výsledek zprávy - "ok" nebo "error". (typ: enum; povolené hodnoty: ok, error)
• msg-id - Id zprávy - Alfanumerický identifikátor zprávy sdílený s IMAP uložištěm; přítomen jen při status="ok". (typ: string)
• mkey - Interní klíč zprávy - Celočíselný identifikátor zprávy ve flexideu; přítomen jen při status="ok". (typ: number)
• dkey - Klíč dokumentu z požadavku - Echo hodnoty dkey z requestového uzlu email, je-li uvedena; přítomno při úspěchu i obou chybových větvích. (typ: string; nepovinný)
• store - Výsledek uložení kopie do IMAP - Přítomen jen byl-li v požadavku send-email uveden folder, a jen ve větvi status="ok": "append"/"stored" při úspěšném volání ukládací funkce (rozlišení dvou dílčích výsledků tohoto volání), "failed" při jeho selhání. (typ: enum; nepovinný; povolené hodnoty: append, stored, failed)
• detail - Popis chyby - "Zpracovani XML mailu se nezdarilo" nebo "Pri odesilani mailu doslo k chybe"; přítomen jen při status="error". Obě tyto chybové větve jsou otevírací/uzavírací dvojice s možností vnořeného uzlu error. (typ: string; nepovinný)

Potomek recipient (0 a vícekrát), jen při verbose="true" na requestu: <recipient email="{string}" status="ok|error"/> – status="error" znamená odmítnutého příjemce. Tento uzel dosavadní dokumentace vůbec nezmiňovala.

Příklady odpovědi

(Zatím bez ověřeného příkladu.)

Chyby a reakce

• <send-email status="error" detail="Atribut profile neobsahuje platnou hodnotu, nebo uzivatel nema predvoleny profil"/> – profile chybí/je neplatný a volající nemá výchozí mailový profil.
• <send-email status="error" detail="Pri zpracovani admin-filteru doslo k chybe"> + vnořený error + </send-email> – selhání admin-filtru na úrovni databáze.
• <send-email status="error" detail="Nemate patricna opravneni"/> – admin-filtr zamítl přístup k danému profilu pro efektivní roli.
• <send-email status="error" detail="Pozadovany profil neexistuje"/> – zadaný profile nemá odpovídající aktivní synchronizační profil v mailové službě.
• <send-email status="error" detail="Mailova sluzba je zastavena"/> – mailová služba serveru neběží.
• <send-email status="error" detail="Transakce byla odvolana"/> / status="skip" detail="Transakce byla preskocena" – standardní transakční vyřazení obálky.
• Uvnitř úspěšně zahájeného zpracování: <email status="error" detail="Zpracovani XML mailu se nezdarilo">…</email> a <email status="error" detail="Pri odesilani mailu doslo k chybe">…</email> – viz „Zpracování“ výše; tyto chyby NEMĚNÍ send-email/@status, které zůstává "ok".
• Výraz pro identifikaci chyb v odpovědi serveru musí kontrolovat obě úrovně: send-email[@status='error'] | send-email/email[@status='error'].

Související požadavky

• test-smtp – otestování SMTP nastavení profilu předem.
• test-imap – otestování IMAP nastavení profilu (relevantní pro ukládání kopie přes folder).