English ▼
Skip to page content Skip to main navigation
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 can receive email at various addresses. Apps send messages using the Mail service and receive messages in the form of HTTP requests initiated by App Engine and posted to the app.

- Sending Mail in Python
- Receiving Mail in Python
- Sending Mail
- Receiving Mail
- Sending Mail with Attachments
- Sending Mail with Headers
- Mail and the Development Server
- Authenticating Mail: DKIM
- Quotas and Limits

## Sending Mail in Python

The `mail.send_mail()` function sends an email message from the application. The `From:` address can be the email address of a registered administrator (developer) of the application, the current user if signed in with Google Accounts, or any valid email receiving address for the app (that is, an address of the form `string@appid.appspotmail.com`).

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 = "Example.com Support <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.

## Receiving Mail in Python

You can set up your app to receive incoming email at string@appid.appspotmail.com addresses. To receive email, you first edit your app's configuration file to include a section that enables incoming mail:

    inbound_services:
    - mail

Incoming email in App Engine works by posting HTTP requests containing MIME data to your app. In your configuration file, you must create mappings from URL paths that represent email addresses to handlers in your app's code:

    - url: /_ah/mail/.+
      script: handle_incoming_email.py
      login: admin

The URL path is `/_ah/mail/` followed by the incoming email address used. The pattern `/_ah/mail/.+` matches all incoming email addresses.

In your app itself, you include the code for the handlers you specified. The email's MIME data is supplied to your app as the contents of an HTTP POST request, and you process this data in your handlers. The Python SDK includes the `InboundEmailMessage` class, a class provided to help you parse email messages in your handlers. You can use `InboundEmailMessage` in your email handler like this:

      from google.appengine.api import mail

      message = mail.InboundEmailMessage(self.request.body)

In addition, the `InboundEmailMessage` class includes attributes for fields in the message.

## Sending Mail

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, as well as a limited set of headers.

For security purposes, the sender address of a message must be the email address of an administrator for the application or any valid email receiving address for the app (see Receiving Mail). The sender can also be the Google Account email address of the current user who is signed in, if the user's account is a Gmail account or is on a domain managed by Google Apps.

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 also send mail using a domain account by adding the domain account as a Developer in the Admin Console. Domain accounts are accounts outside of the Google domain with email addresses that do not end in @gmail.com or @APP-ID.appspotmail.com. It is possible that when you send emails from a domain account using Google servers, automated spam classifiers might believe the email address is being spoofed. If you run into this issue, set the SPF records for the domain to indicate that Google is a trusted source for your email. For instructions on how to do this, see SPF records in the Google Apps help articles.

Note: Your domain (e.g. example.com) needs to be explictly registered with Google Apps and verified before you can create and use domain accounts (e.g. user@example.com). Domain accounts do not need to be explicitly verified, since you will have verified the domain during the registration process. For more information about registering a domain, see Register a new domain.

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").

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.

## Receiving Mail

Your app can receive email at addresses of the following form:

    string@appid.appspotmail.com

Note that even if your app is deployed on a custom domain, your app can't receive email sent to addresses on that domain.

Email messages are sent to your app as HTTP requests. These requests are generated by App Engine and posted to your app. In your app's configuration, you specify handlers that will be called to handle these HTTP requests. In your handlers, you receive the MIME data for email messages, which you then parse into its individual fields.

Email messages are sent to your app as HTTP POST requests using the following URL:

    /_ah/mail/address

where address is a full email address, including domain name.

The ability to receive mail in your app is disabled by default. To enable your app to receive mail, you must specify that you want this service enabled in your `app.yaml` file by including this:

    inbound_services:
    - mail

## Sending Mail with Attachments

An outgoing 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.

The following is a list of MIME types and their corresponding filename extensions allowed for file attachments to an email message. You are not limited to these extensions. If you use an unknown extension, App Engine will assign it the mime type `application/octet-stream`.

MIME Type | Filename Extension(s)
--- | ---
application/msword | doc
application/msword | docx
application/pdf | pdf
application/rss+xml | rss
application/vnd.google-earth.kml+xml | kml
application/vnd.google-earth.kmz | kmz
application/vnd.ms-excel | xls
application/vnd.ms-excel | xlsx
application/vnd.ms-powerpoint | pptx
application/vnd.ms-powerpoint | pps ppt
application/vnd.oasis.opendocument.presentation | odp
application/vnd.oasis.opendocument.spreadsheet | ods
application/vnd.oasis.opendocument.text | odt
application/vnd.sun.xml.calc | sxc
application/vnd.sun.xml.writer | sxw
application/x-gzip | gzip
application/zip | zip
audio/basic | au snd
audio/flac | flac
audio/mid | mid rmi
audio/mp4 | m4a
audio/mpeg | mp3
audio/ogg | oga ogg
audio/x-aiff | aif aifc aiff
audio/x-wav | wav
image/gif | gif
image/jpeg | jpeg jpg jpe
image/png | png
image/tiff | tiff tif
image/vnd.wap.wbmp | wbmp
image/x-ms-bmp | bmp
text/calendar | ics
text/comma-separated-values | csv
text/css | css
text/html | htm html
text/plain | text txt asc diff pot
text/x-vcard | vcf
video/mp4 | mp4
video/mpeg | mpeg mpg mpe
video/ogg | ogv
video/quicktime | qt mov
video/x-msvideo | avi

As a security measure to protect against viruses, you cannot send email attachments or zip files containing any of the following extensions:

- ade
- adp
- bat
- chm
- cmd
- com
- cpl
- exe
- gzip
- hta
- ins
- isp
- jse
- lib
- mde
- msc
- msp
- mst
- pif
- scr
- sct
- shb
- sys
- vb
- vbe
- vbs
- vxd
- wsc
- wsf
- wsh
- zip

## Sending Mail with Headers

An outgoing email can have zero or more extra headers. A header has a name and a value.

For security purposes, the name of a header must be of one of the allowed header names:

- In-Reply-To
- References

## 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.

## Authenticating Mail: DKIM

If your application runs on a custom domain, App Engine can cryptographically sign the emails it sends. This signature says that this mail that purports to be from `emma@example.com` really came from `example.com`. The recipient can check this signature; if the signature is there and correct, the recipient knows that the sender's domain wasn't spoofed. App Engine uses the DKIM protocol to authenticate the sender's domain.

To enable App Engine's DKIM authentication for a custom domain, use the domain's control panel. This control panel is at a location like http://www.google.com/a/cpanel/example.com , replacing example.com with your domain. In the control panel, choose the Advanced Tools tab and then enable DKIM signing.

After you have enabled DKIM, the application will sign the application's outgoing mails if it makes sense for the mail's "From:" address.

If the application sends mail on behalf of an application administrator, it signs the mail.

If the application sends mail on behalf of an address on the custom domain, it signs mail if responding to a request on the custom domain For example, a request on http://example.com/ to send mail on behalf of `emma@example.com`. If the user browses http://appid.appspot.com/ instead of the custom domain, the application won't sign the mail.

## 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 (billable) 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 (billable)
- 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 (billable)
- 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 outgoing mail messages, including attachments | 10 megabytes
maximum size of incoming mail messages, including attachments | 10 megabytes
maximum size of message when an administrator is a recipient | 16 kilobytes