Added lots of example calls.

reaction-mailcreate/README.md

@@ -176,4 +176,125 @@ DFN-CERT,Tobias,Dussa,dussa@dfn-cert.de
 
 ## Example Calls
 
-### 
+Note: In all examples, the option `--dry-run` will be used if necessary, so
+that copy-and-pasting the examples does not lead to e-mails being sent by
+mistake.
+
+The simplest invocation of the script is this:
+```
+./createMails.py
+```
+Assuming that the sample directory is present and containing the sample
+mail template and input list, this call takes all the default values,
+creates a mail for each entry in the default input list, and saves that.
+Since no sender e-mail and webserver address is given, dry-mode is implied,
+so no mails are actually sent, nor is any web call actually made.
+
+The output should look something like this:
+```
+DRY RUN.  Not actually sending e-mails or creating targets, just creating mail files and URLs.
+Writing mail to Mails/Test/DFN-CERT/2024-08-16T10:23:43Z.eml
+```
+
+The minimal set of parameters that must be given is the sender e-mail and
+the target webserver to be used.  To send a mail without any webserver
+reference, set the webserver to the empty string; an minimal example
+invocation that would actually send e-mails (if `--dry-run` was not set) is
+this:
+```
+./createMails.py --dry-run --from "Tobias Dussa <dussa@dfn-cert.de>" --webserver ""
+```
+
+Notice that since no target webserver is specified, the `URL` variable in
+the default mail template does not make much sense, but you can still use
+it -- it will just not contain any complete URL.
+
+To be able to identify individual test runs, you can add an infix to the
+invocation.  This will (by default) insert the infix into several file
+names, in particular, into the input file name; therefore, in order to run
+the following command, you need to copy the sample input file to a new file
+as well.  Note that while the infix is just a positional argument, since it
+begins with a dash in this example, we need to make sure that it is
+interpreted as a positional argument, not as a usage of the `-R` (reply-to)
+parameter by adding two dashes first.
+```
+cp Mails/Test/Input.lst Mails/Test/Input-Run_A.lst
+./createMails.py --dry-run --from "Tobias Dussa <dussa@dfn-cert.de>" --webserver "" -- -Run_A
+DRY RUN.  Not actually sending e-mails or creating targets, just creating mail files and URLs.
+Writing mail to Mails/Test/DFN-CERT/2024-08-16T10:34:11Z-Run_A.eml
+```
+
+Generally, you will likely want to specify the campaign name.  This then
+requires a proper directory with the right input files, so it will not work
+with the sample files, but you can set the campaign name like this:
+```
+./createMails.py --campaign MyCampaign
+```
+The relevant files are then expected to be in `Mails/MyCampaign/`, and
+mail files are written in that directory as well.
+
+The following example modifies the mail subject:
+```
+./createMails.py --subject "This is just a simple mail subject"
+```
+
+Likewise, you can specify a reply-to address to be used with the
+`-R`/`--reply-to` parameter.
+
+To add additional mail recipients to the CC header, you can do this:
+```
+./createMails.py --cc mail@example.com
+```
+
+You can use the same mechanism for BCC recipients and for file attachments.
+All these parameters can be used multiple times to specify multiple
+additional recipients or attachments:
+```
+./createMails.py --bcc foo@example.com --bcc bar@example.com --cc baz@example.com --attach createMails.py
+```
+
+Cryptographic signatures can be added as well.  At the moment, the only
+supported backend is GPG.  The following call will invoke GPG and sign the
+mail with the default key.
+```
+./createMails.py --sign gpg
+```
+
+You can also specify a different key to be used by passing call options to
+the signing command:
+```
+./createMails.py --sign gpg --sign-arg "keyid=0x1234567890ABCDEF"
+```
+
+By default, mails are sent to localhost on port 25 using plain SMTP.  To
+use a different mail server, you need to specify the server to be used:
+```
+./createMails.py --smtpserver smtp.example.com
+```
+
+If you need to log in to send a mail, you can do so as well.  This will
+imply TLS and set the port to 465.  To override this, you need to set the
+port yourself.
+```
+./createMails.py --smtpuser user --smtppass pass
+```
+
+If you do not want to specify the SMTP password on the command line for
+security reasons, you can set the password to a dash, and you will be
+prompted for the password interactively:
+```
+./createMails.py --smtpuser user --smtppass -
+```
+
+An actual invocation will obviously combine a lot of the above parameters:
+```
+./createMails.py --dry-run \
+   --smtpserver smtp.example.com --smtpuser user --smtppass pass \
+   --from "Sender Dude <sender@example.com>" \
+   --cc "CC Recipient <cc@example.com>" \
+   --bcc bcc@example.com \
+   --reply-to reply@example.com \
+   --sign gpg
+   --campaign SampleCommsChallenge2024 \
+   --webserver https://landing.example.com
+```