google.appengine.api.mail module

Sends email on behalf of application.

Provides functions for application developers to provide email services for their applications. Also provides a few utility methods.

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

Bases: google.appengine.api.mail._EmailMessageBase

Interface to sending email messages to all admins via the amil API.

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

Unlike the normal email message, addresses in the recipient fields are ignored and not used for sending.

Example Usage:

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()

It might be desirable for an application to build an admin 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 that 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 though:

attachment = mail.Attachment(‘foo.jpg’, ‘data’, content_id=’<foo>’) attachment == (attachment.filename,

attachment.payload, attachment.content_id)
Attributes:
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)

Check that email is valid.

Args:
email_address: Email 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 email API service.

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

Example Usage:

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()

It might be desirable for an application to build an email in different places throughout the code. For this, 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]
PROPERTIES = set(['body', 'sender', 'to', 'cc', 'bcc', 'headers', 'html', 'reply_to', 'subject', 'attachments'])
ToProto()[source]

Does addition conversion of recipient fields to protocol buffer.

Returns:
MailMessage protocol version of mail message including sender fields.
check_initialized()[source]

Provide additional checks to ensure recipients have been specified.

Raises:
MissingRecipientError when no recipients specified in to, cc or bcc.
update_from_mime_message(mime_message)[source]

Copy information from a mime message.

Update fields for recipients.

Args:
mime_message: email.Message instance to copy information from.
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, and then possibly further encoded using a transfer encoding in that character set. Most of the times, 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.

Attributes:

payload: The original encoded payload. charset: The character set of the encoded payload. None means use

default character set.
encoding: The transfer encoding of the encoded payload. None means
content not encoded.
copy_to(mime_message)[source]

Copy contents to MIME message payload.

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

Args:
mime_message: Message instance to receive new payload.
decode()[source]

Attempt to decode the encoded data.

Attempt to use pythons codec library to decode the payload. All exceptions are passed back to the caller.

Returns:
Binary or unicode version of payload content.
to_mime_message()[source]

Convert to MIME message.

Returns:
MIME message instance of payload.
class google.appengine.api.mail.InboundEmailMessage(mime_message=None, **kw)[source]

Bases: google.appengine.api.mail.EmailMessage

Parsed email object as recevied from external source.

Has 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 Usage:

# 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', 'sender', 'alternate_bodies', 'cc', 'bcc', 'attachments', 'to', 'html', 'reply_to', 'date', 'message_id', 'subject'])
bodies(content_type=None)[source]

Iterate over all bodies.

Args:
content_type: Content type to filter on. Allows selection of only

specific types of content. Can be just the base type of the content type. For example:

content_type = ‘text/html’ # Matches only HTML content. content_type = ‘text’ # Matches text of any kind.
Yields:
Tuple (content_type, payload) for all bodies of message, including body, html and all alternate_bodies in that order.
to_mime_message()[source]

Convert to MIME message.

Adds additional headers from inbound email.

Returns:
MIME message instance of payload.
update_from_mime_message(mime_message)[source]

Update values from MIME message.

Copies over date values.

Args:
mime_message: email.Message instance to copy information from.
google.appengine.api.mail.InvalidEmailReason(email_address, field)

Determine reason why email is invalid.

Args:
email_address: Email to check. field: Field that is invalid.
Returns:
String indicating invalid email reason if there is one, else None.
google.appengine.api.mail.IsEmailValid(email_address)

Determine if email is invalid.

Args:
email_address: Email to check.
Returns:
True if email is valid, else False.
google.appengine.api.mail.MailMessageToMIMEMessage(protocol_message)

Generate a MIMEMultitype message from protocol buffer.

Generates a complete MIME multi-part 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.

Args:
protocol_message: Message PB to convert to MIMEMultitype.
Returns:
MIMEMultitype representing the provided MailMessage.
Raises:
InvalidAttachmentTypeError when the file name of an attachment
google.appengine.api.mail.SendMail(sender, to, subject, body, make_sync_call=<function MakeSyncCall>, **kw)

Sends mail on behalf of application.

Args:

sender: Sender email address as appears in the ‘from’ email line. to: List of ‘to’ addresses or a single address. subject: Message subject string. body: Body of type text/plain. make_sync_call: Function used to make sync call to API proxy. kw: Keyword arguments compatible with EmailMessage keyword based

constructor.
Raises:
InvalidEmailError when invalid email address provided.
google.appengine.api.mail.SendMailToAdmins(sender, subject, body, make_sync_call=<function MakeSyncCall>, **kw)

Sends mail to admins on behalf of application.

Args:

sender: Sender email address as appears in the ‘from’ email line. subject: Message subject string. body: Body of type text/plain. make_sync_call: Function used to make sync call to API proxy. kw: Keyword arguments compatible with EmailMessage keyword based

constructor.
Raises:
InvalidEmailError when invalid email address provided.
google.appengine.api.mail.check_email_valid(email_address, field)[source]

Check that email is valid.

Args:
email_address: Email to check. field: Field to check.
Raises:
InvalidEmailError if email_address is invalid.
google.appengine.api.mail.check_headers_valid(headers)[source]

Check that headers is a valid dictionary for headers.

Args:
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]

Determine reason why email is invalid.

Args:
email_address: Email to check. field: Field that is invalid.
Returns:
String indicating invalid email reason if there is one, else None.
google.appengine.api.mail.invalid_headers_reason(headers)[source]

Determine reason why headers is invalid.

Args:
headers: headers value to check.
Returns:
String indicating invalid headers reason if there is one, else None.
google.appengine.api.mail.is_ascii(string)[source]

Return whether a string is in ascii.

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

Determine if email is invalid.

Args:
email_address: Email to check.
Returns:
True if email is valid, else False.
google.appengine.api.mail.mail_message_to_mime_message(protocol_message)[source]

Generate a MIMEMultitype message from protocol buffer.

Generates a complete MIME multi-part 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.

Args:
protocol_message: Message PB to convert to MIMEMultitype.
Returns:
MIMEMultitype representing the provided MailMessage.
Raises:
InvalidAttachmentTypeError when the file name of an attachment
google.appengine.api.mail.send_mail(sender, to, subject, body, make_sync_call=<function MakeSyncCall>, **kw)[source]

Sends mail on behalf of application.

Args:

sender: Sender email address as appears in the ‘from’ email line. to: List of ‘to’ addresses or a single address. subject: Message subject string. body: Body of type text/plain. make_sync_call: Function used to make sync call to API proxy. kw: Keyword arguments compatible with EmailMessage keyword based

constructor.
Raises:
InvalidEmailError when invalid email address provided.
google.appengine.api.mail.send_mail_to_admins(sender, subject, body, make_sync_call=<function MakeSyncCall>, **kw)[source]

Sends mail to admins on behalf of application.

Args:

sender: Sender email address as appears in the ‘from’ email line. subject: Message subject string. body: Body of type text/plain. make_sync_call: Function used to make sync call to API proxy. kw: Keyword arguments compatible with EmailMessage keyword based

constructor.
Raises:
InvalidEmailError when invalid email address provided.
google.appengine.api.mail.wrapping(wrapped)[source]