# `cement.core.mail`

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': [], 'subject': 'Default Subject Line', 'subject_prefix': '', 'from_addr': 'noreply@example.com', 'cc': [], 'bcc': []}

      Configuration default values

    `interface`

      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.

  Configuration

  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`

  Usage

      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.

  `IMail.``_setup`(app_obj)

    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.
    Returns: | None

  `IMail.``send`(body, **kwargs)

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

    Parameters:

    - 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

    Returns: | Boolean (`True` if message is sent successfully, `False` otherwise)

    Usage

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

        # Overriding configuration defaults
        app.send('My message body'
            to=['john@example.com'],
            from_addr='me@example.com',
            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.