////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Sending emails using SMTP

include::./attributes.adoc[]

This guide demonstrates how your Quarkus application can send emails using an SMTP server.
This is a getting started guide.
Check the xref:mailer-reference.adoc[Quarkus Mailer Reference documentation] for more complete explanation about the mailer and its usage.

== Prerequisites

include::includes/devtools/prerequisites.adoc[]
* The SMTP hostname, port and credentials, and an email address
* cURL

== Architecture

In this guide, we will build an application:

1. exposing an HTTP endpoint,
2. sending email when the endpoint receives an HTTP request.

The application will demonstrate how to send emails using the _imperative_ and _reactive_ mailer APIs.

Attachments, inlined attachments, templating, testing and more advanced configuration are covered in the xref:mailer-reference.adoc[Mailer Reference documentation].

== Solution

We recommend that you follow the instructions in the next sections and create the application step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].

The solution is located in the `mailer-quickstart` {quickstarts-tree-url}/mailer-quickstart[directory].

== Creating the Maven Project

First, we need a project.
Open your browser to https://code.quarkus.io and select the following extensions:

1. RESTEasy Reactive - we use it to expose our HTTP endpoint
2. Mailer - which offer the possibility to send emails
3. Qute - the Quarkus template engine

Alternatively, this https://code.quarkus.io/?a=quarkus-mailer-getting-started&nc=true&e=resteasy-reactive&e=qute&e=mailer&extension-search=mail[link] pre-configures the application.
Click on "Generate your application", download the zip file and unzip it on your file system.
Open the generated project in your IDE.
In a terminal, navigate to the project and start dev mode:

include::includes/devtools/dev.adoc[]

=== Implement the HTTP endpoint

First, create the `src/main/java/org/acme/MailResource.java` file, with the following content:

[source, java]
----
package org.acme;

import io.quarkus.mailer.Mail;
import io.quarkus.mailer.Mailer;
import io.smallrye.common.annotation.Blocking;

import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/mail")                                                          // <1>
public class MailResource {

    @Inject Mailer mailer;                                              // <2>

    @GET                                                                // <3>
    @Blocking                                                           // <4>
    public void sendEmail() {
        mailer.send(
                Mail.withText("quarkus@quarkus.io",                     // <5>
                    "Ahoy from Quarkus",
                    "A simple email sent from a Quarkus application."
                )
        );
    }

}
----
<1> Configure the root path of our HTTP endpoint
<2> Inject the `Mailer` object managed by Quarkus
<3> Create a method that will handle the HTTP GET request on `/mail`
<4> Because we are using RESTEasy Reactive and the _imperative_ mailer, we need to add the `@Blocking` annotation. We will see later the reactive variant.
<5> Create a `Mail` object by configuring the _to_ recipient, the subject and body

The `MailResource` class implements the HTTP API exposed by our application.
It handles `GET` request on `http://localhost:8080/mail.

So, if in another terminal, you run:

[source, bash]
----
> curl http://localhost:8080/mail
----

You should see in the application log something like:

[source, text]
----
INFO  [quarkus-mailer] (executor-thread-0) Sending email Ahoy from Quarkus from null to [quarkus@quarkus.io], text body:
A simple email sent from a Quarkus application.
html body:
<empty>
----

As the application runs in _dev mode_, it simulates the sending of the emails.
It prints it in the log, so you can check that what was about to be sent.

NOTE: This section used the _imperative_ mailer API.
It blocks the caller thread until the mail is sent.

== Using the reactive mailer

The last section use the _imperative_ mailer.
Quarkus also offers a reactive API.


[TIP]
.Mutiny
====
The reactive mailer uses Mutiny reactive types.
If you are not familiar with Mutiny, check xref:mutiny-primer.adoc[Mutiny - an intuitive reactive programming library].
====

In the same class, add:

[source, java]
----
@Inject
ReactiveMailer reactiveMailer;                          // <1>

@GET
@Path("/reactive")                                      // <2>
public Uni<Void> sendEmailUsingReactiveMailer() {       // <3>
    return reactiveMailer.send(                         // <4>
                Mail.withText("quarkus@quarkus.io",
                    "Ahoy from Quarkus",
                    "A simple email sent from a Quarkus application using the reactive API."
                )
        );
}
----
<1> Inject the reactive mailer. The class to import is `io.quarkus.mailer.reactive.ReactiveMailer`.
<2> Configure the path to handle GET request on `/mail/reactive`. Note that because we are using the reactive API, we don't need `@Blocking`
<3> The method returns a `Uni<Void>` which completes when the mail is sent. It does not block the caller thread.
<4> The API is similar to the _imperative_ one except that the `send` method returns a `Uni<Void>`.

Now, in your terminal, run

[source, bash]
----
> curl http://localhost:8080/mail/reactive
----

You should see in the application log something like:

[source, text]
----
INFO  [quarkus-mailer] (vert.x-eventloop-thread-11) Sending email Ahoy from Quarkus from null to [quarkus@quarkus.io], text body:
A simple email sent from a Quarkus application using the reactive API.
html body:
<empty>
----

== Configuring the mailer

It's time to configure the mailer to not simulate the sending of the emails.
The Quarkus mailer is using SMTP, so make sure you have access to a SMTP server.

In the `src/main/resources/application.properties` file, you need to configure the host, port, username, password as well as the other configuration aspect.
Note that the password can also be configured using system properties and environment variables.
See the xref:config-reference.adoc[configuration reference guide] for details.

Here is an example using _sendgrid_:

[source,properties]
----
# Your email address you send from - must match the "from" address from sendgrid.
quarkus.mailer.from=test@quarkus.io

# The SMTP host
quarkus.mailer.host=smtp.sendgrid.net
# The SMTP port
quarkus.mailer.port=465
# If the SMTP connection requires SSL/TLS
quarkus.mailer.ssl=true
# Your username
quarkus.mailer.username=....
# Your password
quarkus.mailer.password=....

# By default, in dev mode, the mailer is a mock. This disables the mock and use the configured mailer.
quarkus.mailer.mock=false
----

Once you have configured the mailer, if you call the HTTP endpoint as shown above, you will send emails.

== Conclusion

This guide has shown how to send emails from your Quarkus application.
The xref:mailer-reference.adoc[mailer reference guide] provides more details about the mailer usage and configuration such as:

* xref:mailer-reference.adoc#attachments[how to add attachments]
* xref:mailer-reference.adoc#html[how to format the email as HTML and use inline attachments]
* xref:mailer-reference.adoc#templates[how to use Qute templates]
* xref:mailer-reference.adoc#testing[how to test applications sending emails]
* xref:mailer-reference.adoc#gmail-specific-configuration[how to configure the mailer to send emails with GMAIL]



