### camel-mail

Interaction with email is provided by the http://camel.apache.org/mail.html[mail,window=_blank] component.

By default, Camel will create its own mail session and use this to interact with your mail server. Since {wildfly} already provides a mail subsystem with all of the relevant support for secure connections, username and password encryption etc, therefore, it is recommended to configure your mail sessions within the {wildfly} configuration and use JNDI to wire them into your Camel endpoints.

#### {wildfly} configuration

First you configure the {wildfly} mail subsystem for the Mail server. The following example adds configuration for Google Mail IMAP and SMTP .

An additional mail-session is configured after the 'default' session.

[source,xml,options="nowrap"]
<subsystem xmlns="urn:jboss:domain:mail:2.0">
    <mail-session name="default" jndi-name="java:jboss/mail/Default">
      <smtp-server outbound-socket-binding-ref="mail-smtp"/>
    </mail-session>

    <mail-session debug="true" name="gmail" jndi-name="java:jboss/mail/gmail">
      <smtp-server outbound-socket-binding-ref="mail-gmail-smtp" ssl="true" username="your-username-here" password="your-password-here"/>
      <imap-server outbound-socket-binding-ref="mail-gmail-imap" ssl="true" username="your-username-here" password="your-password-here"/>
    </mail-session>
</subsystem>

[Note]
====
You can configure `outbound-socket-binding-ref` values of 'mail-gmail-smtp' and 'mail-gmail-imap'.
====

The next step is to configure these socket bindings. You can add additional bindings to the `socket-binding-group` configuration as per the following.

[source,xml,options="nowrap"]
----
<outbound-socket-binding name="mail-gmail-smtp">
  <remote-destination host="smtp.gmail.com" port="465"/>
</outbound-socket-binding>

<outbound-socket-binding name="mail-gmail-imap">
  <remote-destination host="imap.gmail.com" port="993"/>
</outbound-socket-binding>
----

This configures the mail session to connect to host smtp.gmail.com on port 465 and imap.gmail.com on port 993. If you're using a different mail host, then this detail will be different.

#### POP3 Configuration

If you need to configure POP3 sessions, the principles are the same as defined in the examples above.

[source,xml,options="nowrap"]
----
<!-- Server configuration -->
<pop3-server outbound-socket-binding-ref="mail-pop3" ssl="true" username="your-username-here" password="your-password-here"/>

<!-- Socket binding configuration -->
<outbound-socket-binding name="mail-gmail-imap">
  <remote-destination host="pop3.gmail.com" port="993"/>
</outbound-socket-binding>
----

#### Camel route configuration

##### Mail producer
This example uses the SMTPS protocol, together with CDI in conjunction with the camel-cdi component. The Java mail session that you configured within the {wildfly} configuration is injected into a Camel RouteBuilder through JNDI.

###### Route builder SMTPS example
The GMail mail session is injected into a Producer class using the `@Resource` annotation with a reference to the `jndi-name` attribute that you  previously configured. This allows you to reference the mail session on the camel-mail endpoint configuration.

[source,java,options="nowrap"]
----
public class MailSessionProducer {
    @Resource(lookup = "java:jboss/mail/greenmail")
    private Session mailSession;

    @Produces
    @Named
    public Session getMailSession() {
        return mailSession;
    }
}
----

[source,java,options="nowrap"]
public class MailRouteBuilder extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        from("direct:start")
        .to("smtps://smtp.gmail.com?session=#mailSession");
    }
}

To send an email, you can create a ProducerTemplate and send an appropriate body together with the necessary email headers.

[source,java,options="nowrap"]
----
Map<String, Object> headers = new HashMap<String, Object>();
headers.put("To", "destination@test.com");
headers.put("From", "sender@example.com");
headers.put("Subject", "Camel on Wildfly rocks");

String body = "Hi,\n\nCamel on Wildfly rocks!.";

ProducerTemplate template = camelContext.createProducerTemplate();
template.sendBodyAndHeaders("direct:start", body, headers);
----

##### Mail consumer

To receive email you can use an IMAP MailEndpoint. The Camel route configuration looks like the following.

[source,java,options="nowrap"]
public void configure() throws Exception {
   from("imaps://imap.gmail.com?session=#mailSession")
   .to("log:email");
}

#### Security

##### SSL configuration

{wildfly} can be configured to manage Java mail sessions and their associated transports using SSL / TLS. When configuring mail sessions you can configure SSL or TLS on server types:

* smtp-server
* imap-server
* pop-server

By setting attributes `ssl="true"` or `tls="true"`.

##### Securing passwords

It is recommended to not use clear text for passwords within configuration files. You can mask sensitive data using the https://developer.jboss.org/wiki/JBossAS7SecuringPasswords[WildFly Vault,window=_blank].

##### Camel security

Camel endpoint security documentation can be found on the http://camel.apache.org/mail.html[mail,window=_blank]
component guide. Camel also has a http://camel.apache.org/security.html[security summary,window=_blank] page.


#### Code examples on GitHub

An example https://github.com/wildfly-extras/wildfly-camel-examples/tree/master/camel-mail[camel-mail application,window=_blank] is available on GitHub for you to try out sending / receiving email.
