Sending E-Mails

The framework wraps the JavaMail-API with an API that is available to plugins.

Setting Mail credentials

Just like with databases, administrators need to register E-Mail credentials as "mail units".
These are loaded from <config dir>/mail/<unit-name>.json.

mail/test.json

{
  "host": "mail.example.com",
  "port": "25",
  "starttls": true,
  "user": "[email protected]",
  "pass": "secret",
  "from": "[email protected]",
  "properties": {
      "mail.smtp.localhost": "...",
      ... other custom JavaMail properties ...
  }
}

🚧

Sending mail from dynamic IP addresses.

Sending mail messages from dynamic IP addresses, the "HELO" (or "EHLO") commands may be rejected by the mail server on the other end because the reverse DNS record does not match the host name used in those commands.
This can be avoided by setting the abovementioned mail.smtp.localhost option to your actual public IP address. You can look up yours by visiting sites like https://myip.is from your machine.

Using / Sending E-Mails as a developer

E-Mails can be sent using ITransportUnits. These can be injected or retrieved from the IMailService.
Transport units are identified using an id just as persistence units. E-Mail messages can be built using a builder pattern.

Below is a quick, boiled-down example of sending a message via. a transport unit.

Java

public class MailTest {

    @Inject
    @TransportUnit(name = "test")
    private ITransportUnit transportUnit;

    @Listener
    public void onConnected(IBotStateEvent.IConnectStateEvent.IPostConnect event) {
        IMail message = IMail.builder()
                .addSubjectText("Yay! It works!")
                .addText("This is a test-email!")
                .to("[email protected]")
                .build();

        transportUnit.dispatch(message);
    }
}