Cement core mail module.

class cement.core.mail.CementMailHandler(*args, **kw)

Bases: cement.core.handler.CementBaseHandler

Base class that all Mail Handlers should sub-class from.

Configuration Options

This handler supports the following configuration options under a

class Meta

Bases: object

Handler meta-data (can be passed as keyword arguments to the parent class).

config_defaults = {'to': [], 'cc': [], 'subject_prefix': '', 'bcc': [], 'from_addr': 'noreply@example.com', 'subject': 'Default Subject Line'}

Configuration default values


The interface that this handler class implements.

alias of IMail

label = None

String identifier of this handler implementation.

class cement.core.mail.IMail

Bases: cement.core.interface.Interface

This class defines the Mail Handler Interface. Classes that implement this handler must provide the methods and attributes defined below.

Implementations do not subclass from interfaces.


Implementations much support the following configuration settings:

  • to - Default to addresses (list, or comma separated depending on the ConfigHandler in use)
  • from_addr - Default from_addr address
  • cc - Default cc addresses (list, or comma separated depending on the ConfigHandler in use)
  • bcc - Default bcc addresses (list, or comma separated depending on the ConfigHandler in use)
  • subject - Default subject
  • subject_prefix - Additional string to prepend to the subject


from cement.core import mail

class MyMailHandler(object):
    class Meta:
        interface = mail.IMail
        label = 'my_mail_handler'
class IMeta

Bases: object

Interface meta-data.

label = 'mail'

The label (or type identifier) of the interface.

validator(klass, obj)

Interface validator function.


The _setup function is called during application initialization and must ‘setup’ the handler object making it ready for the framework or the application to make further calls to it.

Parameters:app_obj – The application object.
send(body, **kwargs)

Send a mail message. Keyword arguments override configuration defaults (cc, bcc, etc).

  • body (multiline string) – The message body to send
  • to (list) – List of recipients (generally email addresses)
  • from_addr (str) – Address (generally email) of the sender
  • cc (list) – List of CC Recipients
  • bcc (list) – List of BCC Recipients
  • subject (str) – Message subject line

Boolean (True if message is sent successfully, False otherwise)


# Using all configuration defaults
app.send('This is my message body')

# Overriding configuration defaults
app.send('My message body'
    cc=['jane@example.com', 'rita@example.com'],
    subject='This is my subject',
cement.core.mail.mail_validator(klass, obj)

Validates a handler implementation against the IMail interface.