citadel/docs/smtpclient.txt

   1 ====== SMTP Client ======
   2 ===== source files involved: =====
   3
   4
   5 modules/smtp/smtp_clienthandlers.h - SMTP-Client Context struct & functions.
   6 modules/smtp/smtpqueue.h - parsing of Queue mails & respective structures
   7
   8 modules/smtp/serv_smtpqueue.c - queue handling executed by housekeeping thread; de/serialization of Queue-control-messages
   9 modules/smtp/serv_smtpeventclient.c - business logic
  10 modules/smtp/smtp_clienthandlers.c - Protocol logic
  11
  12 msgbase.c - writes spool messages + spoolcontrol files
  13
  14 event_client.c - base event functions
  15
  16 modules/eventclient/serv_eventclient.c - the event queue
  17 modules/c-ares-dns/serv_c-ares-dns.c - nameserver lookup
  18
  19 ===== Spool Control =====
  20 Citadel stores two messages for mail deliveries; the spool control message format is described in delivery-list.txt; its generated in msgbase.c, and de/serialized in serv_smtpqueue.c.
  21 The for Spool-control structures are kept in memory as OneQueItem per Spool-Control-File, and MailQEntry per Recipient of the message.
  22 For each MailQEntry which is still to be delivered, one SmtpOutMsg (containing the AsyncIO context) is spawned. The Jobs are processed in paralell, each job finished triggers an update of the spool control message, so we don't accidently deliver a message twice to one recipient. If the last recipient has succeeded, or permanently failed, the spool-file and the mail-file are removed from the spool room.
  23
  24 ===== Business Logic for one SMTP Connection =====
  25 For each SMTP client one SmtpOutMsg is created as Context; we now live inside the IO-Eventloop. SMTP requires to attempt to connect different servers in different situations; not all errors from remote sides are permanent, or fatal for one delivery attempt. One delivery attempt may involve talking to several SMTP-Servers; maybe the first isn't active or currently not accepting messages.
  26 If citadel runs in relay mode, only the relays are connected; no MX lookup is done.
  27
  28  - MX nameserver lookup; may give several mailservers; IPv4 and IPv6 addresses may be there. If no MX is found, the server is contacted directly.
  29  - Now we have a number of Mailservers we have to iterate over; This is the entry for all subsequent tries for delivery; FailOneAttempt() will decide what to do next.
  30  - one server has to be resolved; A or AAAA record in case of IPv4 or IPv6
  31  - we try to connect the server nonblocking; if we fail to connect in a given time range, the next server has to be tried.
  32  - we now have to wait for the server greeting; we musn't say anything before the server sent a complete line. A timeout may occur, the next server has to be tried, if.
  33  - Now the handlers start to control the logic. A timeout may occur between each of them; Servers may reply with fatal or non fatal or temporary error codes; depending on them
  34    - we fail the conversation with this server, and try the next
  35    - we fail this delivery attempt, and retry later in the next queue run.
  36    - we succeed the delivery of this message.