My notification message

.. _notifications:

Notifications
=============

An interface is provided to send email notifications out to whomever you choose.


.. code-block:: python
    :caption: plain text email

    >>> from pyqalx import QalxSession()
    >>> qalx = QalxSession()

    >>> qalx.notification.add(subject="My notification subject",
    >>>                       to=["someone@example.com"],
    >>>                       message="My notification message")

You can also take advantage of the optional `cc` and `bcc` fields.  You can even
send HTML emails which will be sent as `multipart/alternative`.  Meaning that email
clients that don't support HTML will receive a text representation of your email.


.. code-block:: python
    :caption: HTML email with cc and bcc

    >>> from pyqalx import QalxSession()
    >>> qalx = QalxSession()

    >>> qalx.notification.add(subject="My notification subject",
    >>>                       to=["someone@example.com"],
    >>>                       cc=["someoneelse@example.com"],
    >>>                       bcc=["someonebcc@example.com"],
    >>>                       message="<html><h1>My notification message</h1></html>")

You can even send notifications from any bot step function.  This means you can
easily notify users when a bot completes a job or if it errors during processing.

.. code-block:: python
    :caption: Sending a notification from a bot

    >>> from pyqalx import Bot
    >>>
    >>> bot = Bot(bot_name='my-bot-name')
    >>>
    >>> @bot.process
    >>> def process_func(job):
    >>>     job.session.notification.add(subject="My notification subject",
    >>>                                  to=["someone@example.com"],
    >>>                                  message="My notification message")