Mailer configuration for popular email services

docs/src/main/asciidoc/mailer-reference.adoc

@@ -283,8 +283,70 @@ Check the xref:vertx.adoc[Using Vert.x guide] for further details about these di
 The retrieved `MailClient` is configured using the configuration key presented above.
 You can also create your own instance, and pass your own configuration.
 
+
+== Using SSL with native executables
+
+Note that if you enable SSL for the mailer and you want to build a native executable, you will need to enable the SSL support.
+Please refer to the xref:native-and-ssl.adoc[Using SSL With Native Executables] guide for more information.
+
+== Configuring the SMTP credentials
+
+It is recommended to encrypt any sensitive data, such as the `quarkus.mailer.password`.
+One approach is to save the value into a secure store like HashiCorp Vault, and refer to it from the configuration.
+Assuming for instance that Vault contains key `mail-password` at path `myapps/myapp/myconfig`, then the mailer
+extension can be simply configured as:
+
+[source,properties]
+----
+...
+# path within the kv secret engine where is located the application sensitive configuration
+# This uses the https://github.com/quarkiverse/quarkus-vault extension.
+quarkus.vault.secret-config-kv-path=myapps/myapp/myconfig
+
+...
+quarkus.mailer.password=${mail-password}
+----
+Please note that the password value is evaluated only once, at startup time. If `mail-password` was changed in Vault,
+the only way to get the new value would be to restart the application.
+
+[NOTE]
+Do use Vault, you need the https://github.com/quarkiverse/quarkus-vault[Quarkus Vault] extension.
+More details about this extension and its configuration can be found in the https://quarkiverse.github.io/quarkiverse-docs/quarkus-vault/dev/index.html[extension documentation].
+
+
+[TIP]
+For more information about the Mailer configuration please refer to the <<configuration-reference, Configuration Reference>>.
+
+== Configuring a trust store
+
+If your SMTP requires a trust store, you can configure the trust store as follows:
+
+[source, properties]
+----
+quarkus.mailer.host=...
+quarkus.mailer.port=...
+quarkus.mailer.ssl=true
+quarkus.mailer.trust-store.paths=truststore.jks # the path to your trust store
+quarkus.mailer.trust-store.password=secret # the trust store password if any
+quarkus.mailer.trust-store.type=JKS # the type of trust store if it can't be deduced from the file extension
+----
+
+Quarkus mailer supports JKS, PKCS#12 and PEM trust stores.
+For PEM, you can configure multiple files.
+For JKS and PKCS#12, you can configure the password if any.
+
+`quarkus.mailer.trust-store.type` is optional and allows configuring the type of trust store (among `JKS`, `PEM` and `PKCS`).
+When not set, Quarkus tries to deduce the type from the file name.
+
+NOTE: You can also configure `quarkus.mailer.trust-all=true` to bypass the verification.
+
+[[popular]]
+== Mailer configuration for popular email services
+
+This section provides the configurations to use with popular mail services.
+
 [#gmail-specific-configuration]
-== Gmail specific configuration
+=== Gmail specific configuration
 
 If you want to use the Gmail SMTP server, first create a dedicated password in `Google Account > Security > App passwords` or go to https://myaccount.google.com/apppasswords.
 
@@ -327,55 +389,91 @@ The `quarkus.mailer.auth-methods` configuration option is needed for the Quarkus
 By default, both the mailer and Gmail default to `XOAUTH2` which requires registering an application, getting tokens, etc.
 ====
 
-== Using SSL with native executables
+=== AWS SES - Simple Email Service
 
-Note that if you enable SSL for the mailer and you want to build a native executable, you will need to enable the SSL support.
-Please refer to the xref:native-and-ssl.adoc[Using SSL With Native Executables] guide for more information.
+==== Prerequisites
 
-== Configuring the SMTP credentials
+1. SES Identity Check, follow the process to setup the DKIM verification
+2. Retrieve SMTP endpoint from https://us-east-1.console.aws.amazon.com/ses/home, example: `email-smtp.us-east-1.amazonaws.com`
+3. Create SMTP credentials if needed
+4. If you are in a sandbox, also verify the recipients (using email verification)
 
-It is recommended to encrypt any sensitive data, such as the `quarkus.mailer.password`.
-One approach is to save the value into a secure store like HashiCorp Vault, and refer to it from the configuration.
-Assuming for instance that Vault contains key `mail-password` at path `myapps/myapp/myconfig`, then the mailer
-extension can be simply configured as:
+==== Configuration
 
-[source,properties]
+[source, properties]
 ----
-...
-# path within the kv secret engine where is located the application sensitive configuration
-quarkus.vault.secret-config-kv-path=myapps/myapp/myconfig
+ses.smtp=...
+ses.user=...
+ses.password=...
+ses.from=an email address from the verified domain
 
-...
-quarkus.mailer.password=${mail-password}
+quarkus.mailer.host=${ses.smtp}
+quarkus.mailer.port=587
+quarkus.mailer.username=${ses.user}
+quarkus.mailer.password=${ses.password}
+quarkus.mailer.start-tls=REQUIRED
+quarkus.mailer.login=REQUIRED
+quarkus.mailer.from=${ses.from}
+
+quarkus.mailer.mock=false # In dev mode, prevent from using the mock SMTP server
 ----
-Please note that the password value is evaluated only once, at startup time. If `mail-password` was changed in Vault,
-the only way to get the new value would be to restart the application.
 
-[TIP]
-For more information about the Mailer configuration please refer to the <<configuration-reference, Configuration Reference>>.
+=== MailJet
 
-== Configuring a trust store
+The mailjet integration is used on an SMTP relay.
+You are going to send the email using this SMTP server.
 
-If your SMTP requires a trust store, you can configure the trust store as follows:
+==== Prerequisites
+
+1. Create a mailJet account and the API key / Secret Key
+2. The sender address must be verified (SPF + DKIM) and the email explicitly added to the verified list
+
+==== Configuration
 
 [source, properties]
 ----
-quarkus.mailer.host=...
-quarkus.mailer.port=...
+mailjet.smtp-host=in-v3.mailjet.com
+mailjet.api-key=...
+mailjet.secret-key=...
+mailjet.from=the verified sender address
+
+quarkus.mailer.host=${mailjet.smtp-host}
+quarkus.mailer.port=465
+quarkus.mailer.username=${mailjet.api-key}
+quarkus.mailer.password=${mailjet.secret-key}
+quarkus.mailer.start-tls=OPTIONAL
 quarkus.mailer.ssl=true
-quarkus.mailer.trust-store.paths=truststore.jks # the path to your trust store
-quarkus.mailer.trust-store.password=secret # the trust store password if any
-quarkus.mailer.trust-store.type=JKS # the type of trust store if it can't be deduced from the file extension
+quarkus.mailer.login=REQUIRED
+quarkus.mailer.from=${mailjet.from}
+
+quarkus.mailer.mock=false # In dev mode, prevent from using the mock SMTP server
 ----
 
-Quarkus mailer supports JKS, PKCS#12 and PEM trust stores.
-For PEM, you can configure multiple files.
-For JKS and PKCS#12, you can configure the password if any.
+=== Sendgrid
 
-`quarkus.mailer.trust-store.type` is optional and allows configuring the type of trust store (among `JKS`, `PEM` and `PKCS`).
-When not set, Quarkus tries to deduce the type from the file name.
+==== Prerequisites
 
-NOTE: You can also configure `quarkus.mailer.trust-all=true` to bypass the verification.
+* Follow the instruction to verify the sender domain using DKIM
+
+==== Configuration
+
+[source, properties]
+----
+sendgrid.smtp-host=smtp.sendgrid.net
+sendgrid.username=apikey
+sendgrid.key=...
+
+quarkus.mailer.host=${sendgrid.smtp-host}
+quarkus.mailer.port=465
+quarkus.mailer.username=${sendgrid.username}
+quarkus.mailer.password=${sendgrid.key}
+quarkus.mailer.start-tls=OPTIONAL
+quarkus.mailer.ssl=true
+quarkus.mailer.login=REQUIRED
+quarkus.mailer.from=...
+
+quarkus.mailer.mock=false # In dev mode, prevent from using the mock SMTP server
+----
 
 [[configuration-reference]]
 == Mailer Configuration Reference

docs/src/main/asciidoc/mailer.adoc

@@ -205,6 +205,8 @@ quarkus.mailer.mock=false
 
 Once you have configured the mailer, if you call the HTTP endpoint as shown above, you will send emails.
 
+Other popular mail services are covered in xref:mailer-reference.adoc#popular[the reference guide].
+
 == Conclusion
 
 This guide has shown how to send emails from your Quarkus application.