Skip to page content Skip to main navigation
English | Site Directory

e.g. "templates" or "datastore"

# Mail Python API Overview

App Engine applications can send email messages on behalf of the app's administrators, and on behalf of users with Google Accounts. Apps use the Mail service to send email messages.

- Sending Mail in Python
- Email Messages
- Attachments
- Sending Mail
- Mail and the Development Server
- Quotas and Limits

## Sending Mail in Python

The `mail.send_mail()` function sends an email message from the application. The `From:` address can be either the email address of a registered administrator (developer) of the application, or the current user if signed in with Google Accounts.

The following example sends an email message to the user as confirmation that the user created a new account with the application:

    from google.appengine.api import mail

    class ConfirmUserSignup(webapp.RequestHandler):
      def post(self):
        user_address = self.request.get("email_address")

        if not mail.is_email_valid(user_address):
          # prompt user to enter a valid address

        else:
          confirmation_url = createNewUserConfirmation(self.request)
          sender_address = "support@example.com"
          subject = "Confirm your registration"
          body = """
    Thank you for creating an account!  Please confirm your email address by
    clicking on the link below:

    %s
    """ % confirmation_url

          mail.send_mail(sender_address, user_address, subject, body)

The Python Mail API also includes an object-oriented interface with similar functionality.

## Email Messages

The Mail service can send email messages to one or more recipients. The message contains a subject, a plaintext body, and an optional HTML body. It can also contain file attachments.

For security purposes, the sender address of a message must be the email address of an administrator for the application, or the Google Account email address of the current user who is signed in. The email address can include a "reply to" address, which must also meet these restrictions.

If you want to send email on behalf of the application but do not want to use a single administrator's personal Google Account as the sender, you can create a new Google Account for the application using any valid email address, then add the new account as an administrator for the application. To add an account as an administrator, see the "Developers" section of the Admin Console.

You can use any email address for a recipient. A recipient can be in the message's "to" field or the "cc" field, or the recipient can be hidden from the message header (a "blind carbon copy" or "bcc").

## Attachments

An email message can have zero or more file attachments.

An attachment has a filename and file data. The file data can come from any source, such as an application data file or the datastore. The MIME type of the attachment is determined from the filename.

For security purposes, a file attached to an email messages must be of one of the allowed file types, and its filename must end with an extension that corresponds with its type.

The following is a list of MIME types and their corresponding filename extensions allowed for file attachments to an email message.

MIME Type | Filename Extensions
--- | ---
image/x-ms-bmp | bmp
text/css | css
text/comma-separated-values | csv
image/gif | gif
text/html | htm html
image/jpeg | jpeg jpg jpe
application/pdf | pdf
image/png | png
application/rss+xml | rss
text/plain | text txt asc diff pot
image/tiff | tiff tif
image/vnd.wap.wbmp | wbmp
text/calendar | ics |
text/x-vcard | vcf |

## Sending Mail

When an application calls the Mail service to send a message, the message is queued and the call returns immediately. The Mail service uses standard procedures for contacting each recipient's mail server, delivering the message, and retrying if the mail server cannot be contacted.

If the Mail service cannot deliver a message, or if an recipient's mail server returns a bounce message (such as if there is no account for that address on that system), the error message is sent by email to the address of the sender for the message. The application itself does not receive any notification about whether delivery succeeded or failed.

## Mail and the Development Server

The development server can be configured to send email messages directly from your computer when you test a feature of your app that sends messages. You can configure the development server to use an SMTP server of your choice. Alternatively, you can tell it to use Sendmail, if Sendmail is installed on your computer and set up for sending email.

If you do not configure an SMTP server or enable Sendmail, when your app calls the Mail service, the development server will log the contents of the message, and not send the message.

## Quotas and Limits

Each Mail service request counts toward the Mail API Calls quota.

Each recipient email address for an email message counts toward the Recipients Emailed (adjustable) quota. Each recipient that is an administrator for the application also counts toward the Admins Emailed quota.

Data sent in the body of an email message counts toward the following quotas:

- Outgoing Bandwidth (adjustable)
- Message Body Data Sent

Each attachment included with an email message counts toward the Attachments Sent quota.

Data sent as an attachment to an email message counts toward the following quotas:

- Outgoing Bandwidth (adjustable)
- Attachment Data Sent

For more information on quotas, see Quotas, and the "Quota Details" section of the Admin Console.

In addition to quotas, the following limits apply to the use of the Mail service:

Limit | Amount
--- | ---
maximum size of message, including attachments | 1 megabyte
maximum size of message when an administrator is a recipient | 16 kilobytes