Package web2py :: Package gluon :: Module tools :: Class Mail

[hide private]
[frames] | no frames]

# Class Mail

source code

    object --+
             |
            Mail

Class for configuring and sending emails with alternative text / html body, multiple attachments and encryption support

Works with SMTP and Google App Engine.

Nested Classes | [hide private]

Attachment
Email attachment Arguments: payload: path to file or file-like object with read() method filename: name of the attachment stored in message; if set to None, it will be fetched from payload path; file-like object payload must have explicit filename specified content_id: id of the attachment; automatically contained within < and > content_type: content type of the attachment; if set to None, it will be fetched from filename using gluon.contenttype module encoding: encoding of all strings passed to this function (except attachment body) Content ID is used to identify attachments within the html body; in example, attached image with content ID 'photo' may be used in html message as a source of img tag <img src="cid:photo" />.

Instance Methods | [hide private]

__init__(self, server=global_settings.applications_parent, sender=global_settings.applications_parent, login=global_settings.applications_parent, tls=True)
Main Mail object Arguments: server: SMTP server address in address:port notation sender: sender email address login: sender login name and password in login:password notation or None if no authentication is required tls: enables/disables encryption (True by default) In Google App Engine use: server='gae' For sake of backward compatibility all fields are optional and default to None, however, to be able to send emails at least server and sender must be specified.

source code

send(self, to, subject=`'``None``'`, message=`'``None``'`, attachments=global_settings.applications_parent, cc=global_settings.applications_parent, bcc=global_settings.applications_parent, reply_to=global_settings.applications_parent, encoding=`'``utf-8``'`, raw=True, headers=`{``}`)
Sends an email using data specified in constructor Arguments: to: list or tuple of receiver addresses; will also accept single object subject: subject of the email message: email body text; depends on type of passed object: if 2-list or 2-tuple is passed: first element will be source of plain text while second of html text; otherwise: object will be the only source of plain text and html source will be set to None; If text or html source is: None: content part will be ignored, string: content part will be set to it, file-like object: content part will be fetched from it using it's read() method attachments: list or tuple of Mail.Attachment objects; will also accept single object cc: list or tuple of carbon copy receiver addresses; will also accept single object bcc: list or tuple of blind carbon copy receiver addresses; will also accept single object reply_to: address to which reply should be composed encoding: encoding of all strings passed to this method (including message bodies) headers: dictionary of headers to refine the headers just before sending mail, e.g.

source code

Inherited from `object`: `__delattr__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__str__`

Properties | [hide private]

Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, server=global_settings.applications_parent, sender=global_settings.applications_parent, login=global_settings.applications_parent, tls=True)
(Constructor)

source code

    Main Mail object

    Arguments:

        server: SMTP server address in address:port notation
        sender: sender email address
        login: sender login name and password in login:password notation
               or None if no authentication is required
        tls: enables/disables encryption (True by default)

    In Google App Engine use:

        server='gae'

    For sake of backward compatibility all fields are optional and default
    to None, however, to be able to send emails at least server and sender
    must be specified. They are available under following fields:

        mail.settings.server
        mail.settings.sender
        mail.settings.login

    When server is 'logging', email is logged but not sent (debug mode)

    Optionally you can use PGP encryption or X509:

        mail.settings.cipher_type = None
        mail.settings.sign = True
        mail.settings.sign_passphrase = None
        mail.settings.encrypt = True
        mail.settings.x509_sign_keyfile = None
        mail.settings.x509_sign_certfile = None
        mail.settings.x509_crypt_certfiles = None

        cipher_type       : None
                            gpg - need a python-pyme package and gpgme lib
                            x509 - smime
        sign              : sign the message (True or False)
        sign_passphrase   : passphrase for key signing
        encrypt           : encrypt the message
                         ... x509 only ...
        x509_sign_keyfile : the signers private key filename (PEM format)
        x509_sign_certfile: the signers certificate filename (PEM format)
        x509_crypt_certfiles: the certificates file to encrypt the messages
                              with can be a file name or a list of
                              file names (PEM format)

    Examples:

        #Create Mail object with authentication data for remote server:
        mail = Mail('example.com:25', 'me@example.com', 'me:password')

Overrides: object.__init__

### send(self, to, subject=`'``None``'`, message=`'``None``'`, attachments=global_settings.applications_parent, cc=global_settings.applications_parent, bcc=global_settings.applications_parent, reply_to=global_settings.applications_parent, encoding=`'``utf-8``'`, raw=True, headers=`{``}`)

source code

    Sends an email using data specified in constructor

    Arguments:

        to: list or tuple of receiver addresses; will also accept single
            object
        subject: subject of the email
        message: email body text; depends on type of passed object:
                 if 2-list or 2-tuple is passed: first element will be
                 source of plain text while second of html text;
                 otherwise: object will be the only source of plain text
                 and html source will be set to None;
                 If text or html source is:
                 None: content part will be ignored,
                 string: content part will be set to it,
                 file-like object: content part will be fetched from
                                   it using it's read() method
        attachments: list or tuple of Mail.Attachment objects; will also
                     accept single object
        cc: list or tuple of carbon copy receiver addresses; will also
            accept single object
        bcc: list or tuple of blind carbon copy receiver addresses; will
            also accept single object
        reply_to: address to which reply should be composed
        encoding: encoding of all strings passed to this method (including
                  message bodies)
        headers: dictionary of headers to refine the headers just before
                 sending mail, e.g. {'Return-Path' : 'bounces@example.org'}

    Examples:

        #Send plain text message to single address:
        mail.send('you@example.com',
                  'Message subject',
                  'Plain text body of the message')

        #Send html message to single address:
        mail.send('you@example.com',
                  'Message subject',
                  '<html>Plain text body of the message</html>')

        #Send text and html message to three addresses (two in cc):
        mail.send('you@example.com',
                  'Message subject',
                  ('Plain text body', '<html>html body</html>'),
                  cc=['other1@example.com', 'other2@example.com'])

        #Send html only message with image attachment available from
        the message by 'photo' content id:
        mail.send('you@example.com',
                  'Message subject',
                  (None, '<html><img src="cid:photo" /></html>'),
                  Mail.Attachment('/path/to/photo.jpg'
                                  content_id='photo'))

        #Send email with two attachments and no body text
        mail.send('you@example.com,
                  'Message subject',
                  None,
                  [Mail.Attachment('/path/to/fist.file'),
                   Mail.Attachment('/path/to/second.file')])

    Returns True on success, False on failure.

    Before return, method updates two object's fields:
    self.result: return value of smtplib.SMTP.sendmail() or GAE's
                 mail.send_mail() method
    self.error: Exception message or None if above was successful