Home       Trees       Indices       Help   
web2py Web Framework
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
Instance Methods [hide private]
 
__init__(self, server=1, sender=1, login=1, 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=1, cc=1, bcc=1, reply_to=1, encoding='utf-8')
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) 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.		 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=1, sender=1, login=1, 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=1, cc=1, bcc=1, reply_to=1, encoding='utf-8')

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)

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

   Home       Trees       Indices       Help   
web2py Web Framework
Generated by Epydoc 3.0beta1 on Thu Aug 4 00:47:01 2011 http://epydoc.sourceforge.net