[Note: this page assumes that Mailmin is operating in normal mode. See here for an explanation of restricted mode.]

Once Mailmin has been correctly configured, usage is quite simple. Just compose an email containing system commands and Mailmin directives (explained below), address, sign and encrypt it appropriately, and mail it. Mailmin will receive your mail, decrypt it and verify the signature, and execute the commands it contains via the shell.

Mailmin will collect the commands' output, place it into the body of an email message, sign and encrypt it, and send it back to you. [The current implementation sends it to the address of the sender as given in the incoming messages From: email header.]

[Note that for technical reasons, Mailmin currently invokes a separate shell for each command. To execute multiple commands using the same shell, you can do something like this: place them in a file, attach the file to your message, and in the body of your message include the lines:

@save myfile
/bin/sh < myfile

(The @save Mailmin directive is explained below.)]

You can transfer files to and from the remote system and request web content with the @save, @attach and @wattach Mailmin directives respectively, as explained below.

Mailmin directives

Any line of your message whose first (non-whitespace) character is an '@' will be interpreted as a Mailmin directive; it will be intercepted and processed by Mailmin and not passed on to the shell.

The following directives are currently implemented:

Variable Assignment

Any line of your message whose first (non-whitespace) character is a '$' will be interpreted as a Mailmin variable assignment; it will be intercepted and processed by Mailmin and not passed on to the shell. DO NOT use quotes around the variable value.

For example, if Mailmin has been configured with an archive_type of gzip but you want it to send you some PKZIP style archived web content, you could use the following:

					@at = zip
					@wattach some_url

All (user configurable) Mailmin variables are documented in the sample configuration file.

Exit Codes

Mailmin returns 0 on successful execution, and non-zero if an error occurs:

1 Failure reading specified configuration file, or the file is group or world writeable
2 Failure parsing the message
3 Failure of the initial GnuPG invocation
4 Successful GnuPG invocation, but subsequent rejection of the mail based on a GnuPG key related problem (e.g. an unsigned message, or one signed by an unauthorized key, and Restricted Mode has not been enabled)
5 Failure of the final GnuPG invocation

Note that error codes 1 - 4 imply termination before message processing, while error code 5 (or 0, of course) implies that the message has been processed.

Logging and Debug Mode

Beginning with version 0.4, Mailmin supports robust and flexible logging via the Log::Dispatch bundle, now a dependency. Logging is not enabled by default; see the sample configuration file for details on enabling it and selecting a log level.

Mailmin has had a debug option since version 0.3 (see the sample configuration file). With version 0.4, this has been reimplemented to use the Log::Dispatch system. Without debugging set, nothing is printed to standard error unless a terminal error (one of the conditions resulting in a non-zero error code) occurs. With debugging set, all messages that are logged with even the lowest priority ('debug') are sent to standard error.