taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

challenger-send-email.1.rst (3388B)


      1 challenger-send-email(1)
      2 ########################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **challenger-send-email** - transmit a Challenger TAN by electronic mail
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **challenger-send-email** *ADDRESS*
     16 
     17 
     18 Description
     19 ===========
     20 
     21 **challenger-send-email** transmits a TAN to an e-mail address by handing the
     22 message to the local mail transfer agent via mail(1).
     23 
     24 The command is not normally invoked by hand. It is named in the
     25 ``AUTH_COMMAND`` option of a ``[challenger]`` configuration section (see
     26 challenger.conf(5)), and is executed by challenger-httpd(1) whenever a TAN must
     27 be delivered. The same invocation contract is used by the Anastasis
     28 authorization plugins and by the GNU Taler merchant backend, so the helper may
     29 be executed by any of those services.
     30 
     31 *ADDRESS* is the user-supplied address object, as compact JSON. The field
     32 consulted is ``CONTACT_EMAIL``, and its name derives from the
     33 ``enter-$ADDRESS_TYPE-form`` template on the Challenger side.
     34 
     35 The message to transmit — including the TAN — is read from **standard input**.
     36 It is the ``MESSAGE_TEMPLATE_FILE`` of challenger-httpd(1) after expansion. The
     37 TAN is never passed on the command line.
     38 
     39 Handing a message to a mail transfer agent establishes only that the agent
     40 accepted it for delivery. Whether it reaches the recipient's mailbox is decided
     41 later and asynchronously, and is never reported back. **This helper therefore
     42 never reports confirmed delivery**: a successful run exits with status 201,
     43 meaning accepted for delivery.
     44 
     45 Delivery requires a working local mail transfer agent. The helper does not
     46 configure one.
     47 
     48 
     49 Environment
     50 ===========
     51 
     52 **EMAIL_SUBJECT**
     53    Subject of the mail. Optional; if it is unset or empty, the subject is
     54    ``KYC Challenger``. A subject that is not ASCII is encoded as RFC 2047
     55    encoded words in UTF-8. The helper fails with status 40 if the subject
     56    contains a control character, as a line break would end the ``Subject``
     57    header. The subject is not part of the command line, so other users of the
     58    host cannot see it in the process table; a service that composes a subject
     59    for each message sets it in the environment of each invocation.
     60 
     61 The behaviour of mail(1) and of the local mail transfer agent may also be
     62 affected by the environment of the invoking daemon.
     63 
     64 
     65 Exit Status
     66 ===========
     67 
     68 An exit status of 0, or in the 200 to 210 band, means the TAN was
     69 transmitted, or will be. Any other status means it was not. The success
     70 band starts at 200 rather than at 1 because GNUnet reports a helper it
     71 could not execute as exit status 1, which must not be mistaken for a
     72 delivery.
     73 
     74 **201**
     75    The mail transfer agent accepted the message for delivery. This is the
     76    success case; status 0 is never reported, as delivery to a mailbox cannot be
     77    confirmed.
     78 
     79 **10**
     80    The address is malformed, or the ``CONTACT_EMAIL`` field is missing from the
     81    address object.
     82 
     83 **30**
     84    The local mail transfer agent failed or was unavailable.
     85 
     86 **40**
     87    Invocation error, mail(1) is not installed, or **EMAIL_SUBJECT** contains a
     88    control character.
     89 
     90 **50**
     91    The transmission failed for a reason that could not be classified.
     92 
     93 
     94 See Also
     95 ========
     96 
     97 challenger-send-sms(1), challenger-send-post(1), challenger-httpd(1),
     98 challenger.conf(5), mail(1).
     99 
    100 
    101 Bugs
    102 ====
    103 
    104 Report bugs by using https://bugs.taler.net or by sending electronic
    105 mail to <taler@gnu.org>.