Mailer (Simple Java Mail - Maven master project 7.1.0 API)

```
public interface Mailer
```
Mailing tool created exclusively using MailerRegularBuilder. This class is the facade to most Simple Java Mail functionality which is related to doing things with an email (server not always relevant, like with validation, S/MIME encryption etc.).
The e-mail message structure is built to work with all e-mail clients and has been tested with many different webclients as well as some desktop applications. You can experiment with the various types of emails and resulting mime structure on the Simple Java mail website.
Note: if the batch-module is loaded when building a mailer, it will also register itself with the cluster using the provided or random cluster key, so other mailers using the same cluster key immediately start having access to this new server.
simplejavamail.org

See Also:

MailerRegularBuilder, Email

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`@NotNull EmailGovernance`	`getEmailGovernance()`
`@NotNull OperationalConfig`	`getOperationalConfig()`
`@NotNull ProxyConfig`	`getProxyConfig()`
`@Nullable ServerConfig`	`getServerConfig()`
`jakarta.mail.Session`	`getSession()` In case Simple Java Mail falls short somehow, you can get a hold of the internal `Session` instance to debug or tweak.
`@Nullable TransportStrategy`	`getTransportStrategy()`
`@NotNull CompletableFuture<Void>`	`sendMail(Email email)` Delegates to `sendMail(Email, boolean)`, with `async = false`.
`@NotNull CompletableFuture<Void>`	`sendMail(Email email, boolean async)` Processes an `Email` instance into a completely configured `Message`.
`Future<?>`	`shutdownConnectionPool()` Shuts down the connection pool associated with this `Mailer` instance and closes remaining open connections.
`void`	`testConnection()` Delegates to `testConnection(boolean)` with async == `false`.
`@NotNull CompletableFuture<Void>`	`testConnection(boolean async)` Tries to connect to the configured SMTP server, including (authenticated) proxy if set up.
`boolean`	`validate(Email email)` Validates an `Email` instance.

- Method Detail
  - getSession
```
jakarta.mail.Session getSession()
```
    In case Simple Java Mail falls short somehow, you can get a hold of the internal Session instance to debug or tweak. Please let us know why you are needing this on https://github.com/bbottema/simple-java-mail/issues.
  - testConnection
```
void testConnection()
```
    Delegates to testConnection(boolean) with async == false.
  - testConnection
```
@NotNull
@NotNull CompletableFuture<Void> testConnection(boolean async)
```
    Tries to connect to the configured SMTP server, including (authenticated) proxy if set up.
    Note: synchronizes on the thread for sending mails so that we don't get into race condition conflicts with emails actually being sent.
    
    Returns:
    
    A CompletableFuture that is completed immediately if not async.
  - sendMail
```
@NotNull
@NotNull CompletableFuture<Void> sendMail(Email email)
```
    Delegates to sendMail(Email, boolean), with async = false. This method returns only when the email has been processed by the target SMTP server.
    
    Returns:
    
    A CompletableFuture that is completed immediately if not async.
  - sendMail
```
@NotNull
@NotNull CompletableFuture<Void> sendMail(Email email,
                                                   boolean async)
```
    Processes an Email instance into a completely configured Message.
    Sends the JavaMail Message object using Session.getTransport(). It will call Service.connect() assuming all connection details have been configured in the provided Session instance and finally Transport.sendMessage(Message, jakarta.mail.Address[]).
    Performs a call to Message.saveChanges() as the Sun JavaMail API indicates it is needed to configure the message headers and providing a message id.
    If the email should be sent asynchrounously - perhaps as part of a batch, then a new thread is started using the executor for thread pooling.
    If the email should go through an authenticated proxy server, then the SOCKS proxy bridge is started if not already running. When the last email in a batch has finished, the proxy bridging server is shut down.
    
    Parameters:
    
    email - The information for the email to be sent.
    
    async - If false, this method blocks until the mail has been processed completely by the SMTP server. If true, a new thread is started to send the email and this method returns immediately.
    
    Returns:
    
    A CompletableFuture that is completed immediately if not async.
    
    Throws:
    
    MailException - Can be thrown if an email isn't validating correctly, or some other problem occurs during connection, sending etc.
    
    See Also:
    
    Executors.newFixedThreadPool(int), validate(Email)
  - validate
```
boolean validate(Email email)
          throws MailException
```
    Validates an Email instance. Validation fails if the subject is missing, content is missing, or no recipients are defined or that the addresses are missing for NPM notification flags.
    It also checks for illegal characters that would facilitate injection attacks:
    - http://www.cakesolutions.net/teamblogs/2008/05/08/email-header-injection-security
    - https://security.stackexchange.com/a/54100/110048
    - https://www.owasp.org/index.php/Testing_for_IMAP/SMTP_Injection_(OTG-INPVAL-011)
    - http://cwe.mitre.org/data/definitions/93.html
    Parameters:
    
    email - The email that needs to be configured correctly.
    
    Returns:
    
    Always true (throws a MailException exception if validation fails).
    
    Throws:
    
    MailException - Is being thrown in any of the above causes.
    
    See Also:
    
    EmailValidator
  - shutdownConnectionPool
```
Future<?> shutdownConnectionPool()
```
    Shuts down the connection pool associated with this Mailer instance and closes remaining open connections. Waits until all connections still in use become available again to deallocate them as well.
    Note: In order to shut down the whole connection pool (in case of clustering), each individual Mailer instance should be shutdown.
    Note: This does *not* shut down the executor service if it was provided by the user.
    Note: this is only works in combination with the "Advanced batch processing module".
  - getServerConfig
```
@Nullable
@Nullable ServerConfig getServerConfig()
```
    Returns:
    
    The server connection details. Will be null in case a custom fixed Session instance is used.
    
    See Also:
    
    MailerRegularBuilder.withSMTPServer(String, Integer, String, String)
  - getTransportStrategy
```
@Nullable
@Nullable TransportStrategy getTransportStrategy()
```
    Returns:
    
    The transport strategy to be used. Will be null in case a custom fixed Session instance is used.
    
    See Also:
    
    MailerRegularBuilder.withTransportStrategy(TransportStrategy), EmailValidator
  - getProxyConfig
```
@NotNull
@NotNull ProxyConfig getProxyConfig()
```
    Returns:
    
    The proxy connection details. Will be empty if no proxy is required.
  - getOperationalConfig
```
@NotNull
@NotNull OperationalConfig getOperationalConfig()
```
    Returns:
    
    The operational parameters defined using a mailer builder. Includes general things like session timeouts, debug mode, SSL config etc.
  - getEmailGovernance
```
@NotNull
@NotNull EmailGovernance getEmailGovernance()
```
    Returns:
    
    The effective governance applied to each email (default S/MIME signing, email validator etc.).

Interface Mailer

Method Summary

Method Detail

getSession

testConnection

testConnection

sendMail

sendMail

validate

shutdownConnectionPool

getServerConfig

getTransportStrategy

getProxyConfig

getOperationalConfig

getEmailGovernance