Sending mail

Introduction

Ninja allows you to send mails in a really simple and straightforward manner. All you have to do is to add the dependency to ninja-postoffice and configure your SMTP server in application.conf.

Then you can inject Postoffice and Mail in your application. This allows you to create a new Mail instance and send it via the Postoffice.

Adding the dependency and installing the module

First - add the dependency to your pom.xml:

<dependency>
    <groupId>org.ninjaframework</groupId>
    <artifactId>ninja-postoffice</artifactId>
    <version>NINJA_VERSION_YOU_ARE_USING</version>
</dependency>

and start the module in your Module.java file of your Ninja application via install(new NinjaPostofficeModule(ninjaProperties)).

@Singleton
public class Module extends AbstractModule {
    @Override
    protected void configure() { 
        install(new NinjaPostofficeModule());
    }

}

Configuration and basic usage

onfigure your mail server in application.conf via the following parameters:

smtp.host=...               // Hostname of the smtp server (e.g. smtp.mycompany.com)
smtp.port=...               // Port of the smtp server  (e.g. 465).
smtp.ssl=...                // Whether to enable SSL (true or false, default is false)
smtp.starttls=...           // Whether to enable STARTTLS (true or false, default is false)
smtp.starttls.required=...  // Whether to enforce using STARTTLS (true or false, default is false)
smtp.user=...               // Username to access the smtp server
smtp.password=...           // The password
smtp.debug=...              // Enable logging of a huge amount of debug information (true or false)

If you want to send a mail you can inject the Postoffice and a Provider for Mail into your class.

public class MailController {

    @Inject
    Provider<Mail> mailProvider;

    @Inject
    Postoffice postoffice;

    public void sendMail() {
    
        Mail mail = mailProvider.get();

        // fill the mail with content:
        mail.setSubject("subject");

        mail.setFrom("from1@domain");

        mail.addReplyTo("replyTo1@domain");
        mail.addReplyTo("replyTo2@domain");

        mail.setCharset("utf-8");
        mail.addHeader("header1", "value1");
        mail.addHeader("header2", "value2");

        mail.addTo("to1@domain");
        mail.addTo("to2@domain");

        mail.addCc("cc1@domain");
        mail.addCc("cc2@domain");

        mail.addBcc("bcc1@domain");
        mail.addBcc("bcc2@domain");

        mail.setBodyHtml("bodyHtml");

        mail.setBodyText("bodyText");

        // finally send the mail
		try {
		    postoffice.send(mail);
		} catch (EmailException | AddressException e) {
		    // ...
		}
    }
}

Mail in development and in testing

When Ninja is running in test or dev mode Postoffice will be implemented by PostofficeMockImpl by default.

PostofficeMockImpl does not send mails, but stores mails, so you can check if they would have been sent in reality via getLastSentMail().

PostofficeMockImpl also prints out emails that would have been sent to the system.out. This is nice if you are developing your application but don't want to check your email account to see if something has been sent.

Advanced usage

Specifying own Postoffice implementation

You can override the implementation that will be used via the following parameter in application.conf:

postoffice.implementation=... // Implementation to use for interface Postoffice

If you want to use the real SMTP Postoffice in dev mode (and not the mocked Postoffice by default) you can override that behavior with the parameter:

%dev.postoffice.implementation=ninja.postoffice.commonsmail.PostofficeCommonsmailImpl