taler-docs

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

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

      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 **challenger-send-email** reads no environment variables of its own. The
     53 behaviour of mail(1) and of the local mail transfer agent may be affected by the
     54 environment of the invoking daemon.
     55 
     56 
     57 Exit Status
     58 ===========
     59 
     60 An exit status of 0, or in the 200 to 210 band, means the TAN was
     61 transmitted, or will be. Any other status means it was not. The success
     62 band starts at 200 rather than at 1 because GNUnet reports a helper it
     63 could not execute as exit status 1, which must not be mistaken for a
     64 delivery.
     65 
     66 **201**
     67    The mail transfer agent accepted the message for delivery. This is the
     68    success case; status 0 is never reported, as delivery to a mailbox cannot be
     69    confirmed.
     70 
     71 **10**
     72    The address is malformed, or the ``CONTACT_EMAIL`` field is missing from the
     73    address object.
     74 
     75 **30**
     76    The local mail transfer agent failed or was unavailable.
     77 
     78 **40**
     79    Invocation error, or mail(1) is not installed.
     80 
     81 **50**
     82    The transmission failed for a reason that could not be classified.
     83 
     84 
     85 See Also
     86 ========
     87 
     88 challenger-send-sms(1), challenger-send-post(1), challenger-httpd(1),
     89 challenger.conf(5), mail(1).
     90 
     91 
     92 Bugs
     93 ====
     94 
     95 Report bugs by using https://bugs.taler.net or by sending electronic
     96 mail to <taler@gnu.org>.