Note: Python 2.7 has reached end of support on January 31, 2024. Your existing Python 2.7 applications will continue to run and receive traffic. However, App Engine might block re-deployment of applications that use runtimes after their end of support date. We recommend that you migrate to the latest supported version of Python.

google.appengine.api.mail module

Summary

Sends email on behalf of the application.

This module provides functions for application developers to provide email services for their applications. The module also provides a few utility methods.

class google.appengine.api.mail.AdminEmailMessage(mime_message=None, **kw)source

Bases: google.appengine.api.mail._EmailMessageBase

Interface that sends email messages to all administrators via the Mail API.

This class is used to programmatically build an administrator email message to be sent via the Mail API. To use the class, construct an instance, populate its fields, and call Send().

Unlike normal email messages, addresses in the recipient fields are ignored and not used to send the message.

An AdminEmailMessage can be built completely by the constructor:

AdminEmailMessage(sender='sender@nowhere.com',
                  subject='a subject',
                  body='This is an email to you').Send()

You might want your application to build an administrator email in different places throughout the code. For this, AdminEmailMessage is mutable:

message = AdminEmailMessage()
message.sender = 'sender@nowhere.com'
message.subject = 'a subject'
message.body = 'This is an email to you'
message.check_initialized()
message.send()

class google.appengine.api.mail.Attachment(*args, **kwds)source

Bases: object

Attachment object.

An Attachment object is largely interchangeable with a (filename, payload) tuple.

Note:

The behavior is a bit asymmetric with respect to unpacking and equality comparison. An Attachment object without a content ID will be equivalent to a (filename, payload) tuple. An Attachment with a content ID will unpack to a (filename, payload) tuple, but will compare unequally to that tuple.

Thus, the following comparison will succeed:

attachment = mail.Attachment('foo.jpg', 'data')
filename, payload = attachment
attachment == filename, payload

…while the following will fail:

attachment = mail.Attachment('foo.jpg', 'data', content_id='<foo>')
filename, payload = attachment
attachment == filename, payload

The following comparison will pass:

attachment = mail.Attachment('foo.jpg', 'data', content_id='<foo>')
attachment == (attachment.filename,
               attachment.payload,
               attachment.content_id)

filename: The name of the attachment.

payload: The attachment data.

content_id: Optional; the content ID for this attachment. Keyword only.

google.appengine.api.mail.CheckEmailValid(email_address, field)source

Verifies whether an email is valid.

Parameters

email_address – Email address to check.
field – Field to check.

Raises

InvalidEmailError – If email_address is invalid.

class google.appengine.api.mail.EmailMessage(mime_message=None, **kw)source

Bases: google.appengine.api.mail._EmailMessageBase

Main interface to the Mail API service.

This class is used to programmatically build an email message to send via the Mail API. To use this class, construct an instance, populate its fields and call Send().

An EmailMessage can be built completely by the constructor:

EmailMessage(sender='sender@nowhere.com',
             to='recipient@nowhere.com',
             subject='a subject',
             body='This is an email to you').Send()

You might want your application to build an email in different places throughout the code. For this usage, EmailMessage is mutable:

message = EmailMessage()
message.sender = 'sender@nowhere.com'
message.to = ['recipient1@nowhere.com', 'recipient2@nowhere.com']
message.subject = 'a subject'
message.body = 'This is an email to you'
message.check_initialized()
message.send()

CheckInitialized()source: Ensures that recipients have been specified.

PROPERTIES = set(['body', 'amp_html', 'sender', 'to', 'cc', 'bcc', 'attachments', 'headers', 'html', 'reply_to', 'subject'])

ToProto()source

Performs more conversion of recipient fields to the protocol buffer.

Returns

The MailMessage protocol version of the mail message, including sender fields.

check_initialized()source

Provides additional checks to ensure that recipients have been specified.

Raises

MissingRecipientError – If no recipients are specified in ‘To’, ‘Cc’, or ‘Bcc’.

update_from_mime_message(mime_message)source

Copies information for recipients from a MIME message.

Parameters

mime_message – The email.Message instance from which to copy information.

class google.appengine.api.mail.EncodedPayload(payload, charset=None, encoding=None)source

Bases: object

Wrapper for a payload that contains encoding information.

When an email is received, it is usually encoded using a certain character set, then possibly further encoded using a transfer encoding in that character set. Most of the time, it is possible to decode the encoded payload as-is; however, in the case where it is not, the encoded payload and the original encoding information must be preserved.

payload: The original encoded payload.

charset: The character set of the encoded payload. To specify that you want to use the default character set, set this argument to None.

encoding: The transfer encoding of the encoded payload. To specify that you do not want the content to be encoded, set this argument to None.

copy_to(mime_message)source

Copies the contents of a message to a MIME message payload.

If no content transfer encoding is specified and the character set does not equal the overall message encoding, the payload will be base64-encoded.

Parameters

mime_message – Message instance that will receive the new payload.

decode()source

Attempts to decode the encoded data.

This function attempts to use Python’s codec library to decode the payload. All exceptions are passed back to the caller.

Returns

The binary or Unicode version of the payload content.

to_mime_message()source

Converts a message to a MIME message.

Returns

The MIME message instance of the payload.

class google.appengine.api.mail.InboundEmailMessage(mime_message=None, **kw)source

Bases: google.appengine.api.mail.EmailMessage

Receives a parsed email as it is recevied from an external source.

This class makes use of a date field and can store any number of additional bodies. These additional attributes make the email more flexible as required for incoming mail, where the developer has less control over the content.

Example:

# Read mail message from CGI input.
message = InboundEmailMessage(sys.stdin.read())
logging.info('Received email message from %s at %s',
             message.sender,
             message.date)
enriched_body = list(message.bodies('text/enriched'))[0]
# ... Do something with body ...

ALLOW_BLANK_EMAIL = True

PROPERTIES = frozenset(['body', 'amp_html', 'sender', 'alternate_bodies', 'cc', 'bcc', 'to', 'html', 'reply_to', 'date', 'subject', 'message_id', 'attachments'])

bodies(content_type=None)source

Iterates over all bodies.

Parameters

content_type –

Content type on which to filter. This argument allows you to select only specific types of content. You can use the base type or the content type.

For example:

content_type = 'text/html'  # Matches only HTML content.
content_type = 'text'       # Matches text of any kind.

Yields

A (content_type, payload) tuple for all bodies of a message, including the body, HTML, and all alternate_bodies, in that order.

to_mime_message()source

Converts a message to a MIME message.

This function adds additional headers from the inbound email.

Returns

The MIME message instance of a payload.

update_from_mime_message(mime_message)source

Updates the values of a MIME message.

This function copies over date values.

Parameters

mime_message – The email.Message instance from which you want to copy information.

google.appengine.api.mail.InvalidEmailReason(email_address, field)source

Determines the reason why an email is invalid.

Parameters

email_address – Email address to check.
field – Field that is invalid.

Returns

A string that indicates the reason why an email is invalid; otherwise returns None.

google.appengine.api.mail.IsEmailValid(email_address)source

Determines whether an email address is invalid.

Parameters

email_address – Email address to check.

Returns

True if the specified email address is valid; otherwise returns False.

google.appengine.api.mail.MailMessageToMIMEMessage(protocol_message)source

Generates a MIMEMultipart message from a MailMessage protocol buffer.

This function generates a complete MIMEMultipart email object from a MailMessage protocol buffer. The body fields are sent as individual alternatives if they are both present; otherwise, only one body part is sent.

Multiple entry email fields, such as ‘To’, ‘Cc’, and ‘Bcc’ are converted to a list of comma-separated email addresses.

Parameters

protocol_message – Message protocol buffer to convert to a MIMEMultipart message.

Returns

A MIMEMultipart message that represents the provided MailMessage.

Raises

InvalidAttachmentTypeError – If the file type of the attachment is invalid.

google.appengine.api.mail.SendMail(sender, to, subject, body, make_sync_call=MakeSyncCall, **kw)source

Sends mail on behalf of the application.

Parameters

sender – Sender email address as it appears in the ‘From’ email line.
to – List of one or more ‘To’ addresses.
subject – Message subject string.
body – Plain-text body.
make_sync_call – Function used to make a sync call to an API proxy.
**kw – Keyword arguments that are compatible with the EmailMessage keyword based constructor.

Raises

InvalidEmailError – If an invalid email address was specified.

google.appengine.api.mail.SendMailToAdmins(sender, subject, body, make_sync_call=MakeSyncCall, **kw)source

Sends email to administrators on behalf of the application.

Parameters

sender – Sender email address as it appears in the ‘From’ email line.
subject – Message subject string.
body – Plain-text body.
make_sync_call – Function used to make a sync call to an API proxy.
**kw – Keyword arguments that are compatible with the EmailMessage keyword based constructor.

Raises

InvalidEmailError – If an invalid email address was specified.

google.appengine.api.mail.check_email_valid(email_address, field)source

Verifies whether an email is valid.

Parameters

email_address – Email address to check.
field – Field to check.

Raises

InvalidEmailError – If email_address is invalid.

google.appengine.api.mail.check_headers_valid(headers)source

Checks that headers is a valid dictionary for a header.

Parameters

headers – The value to check for the headers.

Raises

InvalidEmailError – If headers is invalid.

google.appengine.api.mail.invalid_email_reason(email_address, field)source

Determines the reason why an email is invalid.

Parameters

email_address – Email address to check.
field – Field that is invalid.

Returns

A string that indicates the reason why an email is invalid; otherwise returns None.

google.appengine.api.mail.invalid_headers_reason(headers)source

Determines the reason why a header is invalid.

Parameters

headers – Header value to check.

Returns

A string that indicates the reason that the headers are invalid if the reason can be determined; otherwise returns None.

google.appengine.api.mail.is_ascii(string)source: Returns whether a string is in ASCII.

google.appengine.api.mail.is_email_valid(email_address)source

Determines whether an email address is invalid.

Parameters

email_address – Email address to check.

Returns

True if the specified email address is valid; otherwise returns False.

google.appengine.api.mail.mail_message_to_mime_message(protocol_message)source

Generates a MIMEMultipart message from a MailMessage protocol buffer.

Multiple entry email fields, such as ‘To’, ‘Cc’, and ‘Bcc’ are converted to a list of comma-separated email addresses.

Parameters

protocol_message – Message protocol buffer to convert to a MIMEMultipart message.

Returns

A MIMEMultipart message that represents the provided MailMessage.

Raises

InvalidAttachmentTypeError – If the file type of the attachment is invalid.

google.appengine.api.mail.send_mail(sender, to, subject, body, make_sync_call=MakeSyncCall, **kw)source

Sends mail on behalf of the application.

Parameters

sender – Sender email address as it appears in the ‘From’ email line.
to – List of one or more ‘To’ addresses.
subject – Message subject string.
body – Plain-text body.
make_sync_call – Function used to make a sync call to an API proxy.
**kw – Keyword arguments that are compatible with the EmailMessage keyword based constructor.

Raises

InvalidEmailError – If an invalid email address was specified.

google.appengine.api.mail.send_mail_to_admins(sender, subject, body, make_sync_call=MakeSyncCall, **kw)source

Sends email to administrators on behalf of the application.

Parameters

sender – Sender email address as it appears in the ‘From’ email line.
subject – Message subject string.
body – Plain-text body.
make_sync_call – Function used to make a sync call to an API proxy.
**kw – Keyword arguments that are compatible with the EmailMessage keyword based constructor.

Raises

InvalidEmailError – If an invalid email address was specified.

google.appengine.api.mail.wrapping(wrapped)source

A decorator that decorates a decorator’s wrapper.

This decorator makes it easier to debug code that is heavily decorated.

Parameters

wrapped – The decorated function that you are trying to debug.

Returns

A function with __name__, __doc__, and ___dict__ remapped to the respective versions of the wrapped function to make debugging easier.

google.appengine.api.mail module

Summary

Contents