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>.