Introduction
Amdatu Email provides a service abstraction for sending email. Currently, it provides implementations to send emails through Amazon’s Simple Email Service, through a configured SMTP server, as well as a mock implementation for use in test scenario’s.
How to use
Deployment
Deploy the org.amdatu.email.impl and preferred email transport bundle; org.amdatu.email.smtp or org.amdatu.email.aws with your application and inject the EmailService into components as desired. The EmailService then allows you to send emails through the configured email server.
Configuration
The EmailService must and an EmailTransportSerivce be configured before it can be used. Once an EmailService is configured, you can use it to send emails using a simple builder pattern. Note that these configurations are mandatory in order to make use of the email service! In the following sections, the configuration and usage of the different implementations are explained in more detail.
Email Service
The Amdatu email service is configured by providing a configuration for the PID org.amdatu.email
Property |
Type |
Required |
Description |
Default value |
whitelist |
String |
yes |
Comma separated list of email addres patterns that are allowed to send email to. |
- |
AWS Transport
AWSEmailService is configured by providing a configuration for the PID org.amdatu.email.aws.
Property |
Type |
Required |
Description |
Default value |
aws-key |
String |
yes |
The AWS key |
- |
aws-secret |
String |
yes |
The AWS secret belonging to the AWS key |
- |
aws-region |
String |
no |
The AWS region used to send email |
The AWS default region |
SMTP Transport
SMTPEmailService is configured by providing a configuration for the PID org.amdatu.email.smtp.
Property |
Type |
Required |
Description |
Default value |
smtp-host |
String |
yes |
The SMTP server |
- |
smtp-user |
String |
yes |
The SMTP server’s username |
- |
smtp-password |
String |
yes |
The user’s password |
- |
smtp-port |
Integer |
no |
The SMTP server’s port |
25 |
smtp-use-ssl |
Boolean |
no |
Whether SSL should be used |
false |
smtp-use-from-name |
String |
no |
The sender’s name |
Amdatu Mail Service |
smtp-use-from-email |
String |
no |
The sender’s email address |
Examples
AWS Email Server
The following example shows how to send an email through the configured AWSEmailService:
instance.send(Message.Builder.create()
.recipient("success@simulator.amazonses.com")
.htmlBody("test")
.subject("test")
.from("test@amdatu.com").build());SMTP Email Server
The following example shows how to send an email through the configured SMTPEmailService:
String testBody = "Amdatu Mail Service Test";
String testSubject = "Test Message";
instance.send(Message.Builder.create()
.recipient("someone@example.com")
.textBody(testBody)
.subject(testSubject)
.from("test@amdatu.org").build());Components
Amdatu Email provides the following components:
Bundle |
Required |
Description |
org.amdatu.email.api |
yes |
Provides the EmailService API |
org.amdatu.email.impl |
yes |
Provides the EmailService implementation |
org.amdatu.email.aws |
no* |
Provides an implementation to send email through a configured AWS account |
org.amdatu.email.smtp |
no* |
Provides an implementation to send email through a configured SMTP server |
org.amdatu.email.mock |
no* |
Provides a mock implementation which outputs sent messages to the LogService |
* At least one backend is required at runtime
Dependencies
The following table provides an overview of the required and optional dependencies for Amdatu Email:
Bundle |
Required |
Description |
org.apache.felix.dependencymanager |
yes |
Apache Felix Dependency Manager is used internally by all Amdatu components |
Implementation of Config Admin (e.g. org.apache.felix.configadmin) |
yes |
Used to configure data sources |
OSGi LogService (e.g. Apache Felix LogService) |
no |
Used for logging purposes |
joda-time |
no |
Used by org.amdatu.email.aws |
org.apache.commons.codec |
no |
Used by org.amdatu.email.aws |
org.apache.httpcomponents.httpclient |
no |
Used by org.amdatu.email.aws |
org.apache.httpcomponents.httpcore |
no |
Used by org.amdatu.email.aws |
Even though you are free to provide your own implementations, all dependencies (as the given examples where applicable) can be resolved from the Amdatu dependencies repository.
System package dependencies
Please note that the EmailServices depend on various system packages:
The lines below can be used to resolve the system package dependencies required when running the corresponding EmailService implementation:
SMTP email bundle: -runsystempackages: sun.security.util
AWS email bundle:-runsystempackages: javax.mail,javax.mail.internet,javax.crypto,javax.net.ssl,javax.crypto.spec,javax.swing,javax.xml.bind,javax.xml.datatype,javax.security.auth.x500,javax.swing.border,org.ietf.jgss,javax.xml.namespace,javax.swing.event,javax.swing.tree,javax.xml.parsers,javax.xml.stream,javax.xml.stream.events,javax.xml.xpath,org.w3c.dom,org.w3c.dom.bootstrap,org.w3c.dom.ls,org.xml.sax,org.xml.sax.helpers
resources.adoc