This guide describes how to use the Mail API to send mail.

<br />

The Mail API provides two ways to send an email message: the
[`mail.send_mail()`](https://docs.cloud.google.com/appengine/docs/standard/python3/reference/services/bundled/google/appengine/api/mail/SendMail)
function and the [`EmailMessage`](https://docs.cloud.google.com/appengine/docs/standard/python3/reference/services/bundled/google/appengine/api/mail/EmailMessage)
class.

Sending is asynchronous: the `mail.send_mail()` function and the
`EmailMessage.send()` method transmit the message data to the mail
service, then return. The mail service queues the message, then attempts to
send it, retrying if the destination mail server is unavailable. Errors and
bounce messages are sent to the sender address for the email message.

<br />

## Before you begin

Register your sender emails as authorized senders. For more information, see
[who can send email](https://docs.cloud.google.com/appengine/docs/standard/services/mail#who_can_send_mail).

<br />

## Sending mail with `mail.send_mail()`

To send mail using the [`mail.send_mail()`](https://docs.cloud.google.com/appengine/docs/standard/python3/reference/services/bundled/google/appengine/api/mail/SendMail) function, use the fields of the
email message as parameters, including the sender, the recipients, the subject
and the body of the message. For example:

        mail.send_mail(sender=sender_address,
                       to="Albert Johnson <Albert.Johnson@example.com>",
                       subject="Your account has been approved",
                       body="""Dear Albert:

    Your example.com account has been approved.  You can now visit
    http://www.example.com/ and sign in using your Google Account to
    access new features.

    Please let us know if you have any questions.

    The example.com Team
    """)

## Sending mail with `EmailMessage`

To send mail using objects with the
[`EmailMessage`](https://docs.cloud.google.com/appengine/docs/standard/python3/reference/services/bundled/google/appengine/api/mail/EmailMessage)
class, pass the fields of the email message to the `EmailMessage` constructor
and use attributes of the instance to update message.

The [`EmailMessage.send()`](https://docs.cloud.google.com/appengine/docs/standard/python3/reference/services/bundled/google/appengine/api/mail/EmailMessage#Send) method sends the email message
represented by the instance's attributes. An application can re-use an
`EmailMessage` instance by modifying attributes and calling the `send()` method
again.

        message = mail.EmailMessage(
            sender=sender_address,
            subject="Your account has been approved")

        message.to = "Albert Johnson <Albert.Johnson@example.com>"
        message.body = """Dear Albert:

    Your example.com account has been approved.  You can now visit
    http://www.example.com/ and sign in using your Google Account to
    access new features.

    Please let us know if you have any questions.

    The example.com Team
    """
        message.send()

## Sending bulk mail

See the [Bulk mail guidelines](https://docs.cloud.google.com/appengine/docs/standard/services/mail/bulk-mail) for considerations around sending bulk
email.

Learn more about the migration considerations for Mail API in the [Mail handlers](https://docs.cloud.google.com/appengine/docs/standard/python3/services/mail) guide.

<br />