Simple Java Mail CLI

Simple Java Mail exposes the complete builder API as CLI commands, which is to say everything you can do with Simple Java Mail in Java, you can also do that in a terminal.

From builder API to CLI commands

To support CLI, the commands and options are generated using Picocli's Java API and Therapi's Javadoc bundler. Together and with a lot of custom glue Simple Java Mail's builder API is traversed and converted into CLI commands.

The great benefit from this is that new builder API is supported by CLI automagically and the documentation is still centralized in the builder API, providing a consistent experience.

How to use
Usage help
@-files
Configuring properties
Configuring logging
Invoking CLI manually
Or by Maven

How to use

To use Simple Java Mail CLI, Download and expand the standalone-cli package and execute the sjm script. Included in the package are all dependencies and two helper scripts for Windows and Unix (generated by standard Maven plugins).

The flags are a bit verbose, but then it supports the complete builder API!


      sjm
      sjm --help
      sjm send
          --email:startingBlank
          --email:from "Mr. Candy" mrcandy@candystore.com
          --email:withSubject "About those tongue twisters"
          --email:to "Sweet Cheeks" "sweet.cheeks@candystore.com"
          --email:cc "Candy Research Group" "<james@candy-insights.com>;<jean@candy-insights.com>"
          --email:bcc "box1 <info-box@candystore.com>,box2 <reminders@candystore.com>"
          --email:withPlainText "I discovered a new flavor! (..)"
          --mailer:withSMTPServer "my-smtp-server.com" 1234 "myuser" "mypass"
          --mailer:withTransportStrategy "SMTP_TLS"

You can also check the demo code included in the sources.

Usage Help

You can get usage information displayed on any level:

Global level	`--help`	informs about available commands
Command level	`send --help`	informs about options available for the "send" command
Option level	`send --email:withSubject--help`	displays usage help for the "withSubject" option

@-files

If you run into a character limit in your console, you can also use "argument files" or "@-files", which is supported in Picocli, the library used under the hood:


      # file /home/foo/args
      --email:withSubject "My Subject"
      --mailer:withSMTPServer host=...
      --other arguments

The command sjm @/home/foo/args then is expanded to:


      sjm --email:withSubject "My Subject" --mailer:withSMTPServer host=... --other arguments

Quoting the Picocli documentation:

This feature is similar to the 'Command Line Argument File' processing supported by gcc, javadoc and javac. The documentation for these tools shows further examples.

From picocli 3.8.1, a simpler argument file format is also supported where every line (except comment lines) is interpreted as a single argument. Arguments containing whitespace do not need to be quoted, but it is not possible to have arguments with embedded newlines.

Set system property picocli.useSimplifiedAtFiles without a value or with value "true" (case-insensitive) to enable this simpler argument file format. This simplified format is similar to the argument file format supported by JCommander.

Configuring properties

With the provided scripts, anything added to the \etc folder is visible on the classpath. In the current release, you can add your simplejavamail.properties there and it will be picked up.

Folder where to put Simple Java Mail properties and logging config for use in CLI

Configuring logging

In the current release, log4j2 properties as supported and you can simply edit the provided log4j2.xml in the /etc folder (see above).

Invoking CLI manually

If you wish to directly invoke the CLI from the jar or class files, CLI support for Java libraries works just like any other Java static void main invocation:

java -cp all;the;jars.jar org.simplejavamail.cli.SimpleJavaMail --help

Simple Java Mail's own main jar should be on the classpath of course, as well as all non-optional dependencies, the optional cli-module dependency and its dependencies.

You can add a simplejavamail.properties file to the classpath this way which will automatically be picked for defaults and configuration.

Or by Maven

Alternatively, you can also let Maven deal with the dependencies, by invoking the maven-exec plugin.

mvn exec:java -Dexec.mainClass="org.simplejavamail.cli.SimpleJavaMail" -Dexec.args="--help"

Or by configuring it in your POM:


<build>
  <plugins>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>exec-maven-plugin</artifactId>
      <version>1.6.0</version>
      <executions>
        <execution>
          <goals><goal>java</goal></goals>
        </execution>
      </executions>
      <configuration>
        <mainClass>org.simplejavamail.cli.SimpleJavaMail</mainClass>
        <arguments>
          <argument>--help</argument>
        </arguments>
      </configuration>
    </plugin>
  </plugins>
</build>

mvn exec:java