google.appengine.api.mail module

Summary

Sends email on behalf of application.

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

Contents

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

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

Check that email is valid.

Parameters
  • 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.

Parameters

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.

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.

Parameters

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.

Parameters

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.

Parameters

mime_message -- email.Message instance to copy information from.

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

Determine reason why email is invalid.

Parameters
  • 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)source

Determine if email is invalid.

Parameters

email_address -- Email to check.

Returns

True if email is valid, else False.

google.appengine.api.mail.MailMessageToMIMEMessage(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.

Parameters

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=MakeSyncCall, **kw)source

Sends mail on behalf of application.

Parameters
  • 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=MakeSyncCall, **kw)source

Sends mail to admins on behalf of application.

Parameters
  • 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.

Parameters
  • 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.

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

Determine reason why email is invalid.

Parameters
  • 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.

Parameters

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.

Parameters

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.

Parameters

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=MakeSyncCall, **kw)source

Sends mail on behalf of application.

Parameters
  • 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=MakeSyncCall, **kw)source

Sends mail to admins on behalf of application.

Parameters
  • 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

Send feedback about...