Keg-Mail 0.3.1
A mail sending library for keg applications
License: BSD

Keg-Mail
#########

Keg-Mail is a basic wrapper around Flask-Mail which gives some added support for
templates.

It is not finished by any means and in some ways provides little additional
benefit over Flask-Mail.


Usage
=====

.. code::

  $ pip install keg-mail


Initialize Keg-Mail in your application

.. code::

  import flask
  import keg_mail
  from keg.signals import app_ready
  from keg import Keg

  bp = flask.blueprint('main', __name__)
  mail = keg_mail.KegMail()

  class App(Keg):
    use_blueprints = [bp]


Initialize the extension with the application

.. code::

  @app_ready.connect
  def init_extensions(app):
      """Init custom extensions used by this application"""

      mail.init_app(app)


Define email content

.. code::

  import keg_mail

  hello_world_content = keg_mail.EmailContent(
    text='Hello {name}!'
    html='<h1>Hello {name}!</h1>'
  )


Send the email

.. code::

  from app import mail
  import app.emails as emails
  import keg_mail

  bp.route('/')
  def index():
      mail.send_email(
          'you@something.com',
          keg_mail.Email(
            subject="Hello {name}!",
            content=emails.hello_world_content,
          ).format(name='You")
      )


Test the email

.. code::

  from app import mail

  def test_send_mail():
      with mail.record_messages() as outbox:
          resp = app.test_client.get('/')
          assert len(outbox) == 1
          assert outbox[0].subject == "Hello You!"
          assert outbox[0].body == "Hello You!"


Mailgun-specific options
------------------------

Mailgun supports various options such as tagging, user-defined variables, etc.
These can be added via a ``mailgun_opts`` dictionary that can be passed to the
app's mail engine's ``send`` method directly:

.. code::

    flask.current_app.mail.send(
        msg,
        mailgun_opts={
            'v:user_name': 'John Doe',
            'v:user_id': 100,
        },
    )


Changelog
=========

0.3.1 released 2024-06-21
-------------------------

- resolve missed signal signature change (52fcc11_)

.. _52fcc11: https://github.com/level12/keg-mail/commit/52fcc11


0.3.0 released 2024-06-21
-------------------------

- automatically pass reply-to header to Mailgun (18fb53f_)
- support flask-mail 0.10.0 changes to signal pattern (3cfe430_)

.. _18fb53f: https://github.com/level12/keg-mail/commit/18fb53f
.. _3cfe430: https://github.com/level12/keg-mail/commit/3cfe430


0.2.4 released 2022-11-10
-------------------------

- allow additional mailgun API options to be sent through send (d35e23d_)
- update CI setup and add python 3.10 (5552cd2_)

.. _d35e23d: https://github.com/level12/keg-mail/commit/d35e23d
.. _5552cd2: https://github.com/level12/keg-mail/commit/5552cd2


0.2.3 released 2020-07-22
-------------------------

- Handle timestamps parsed as decimals in Mailgun event JSON (6a03528_)

.. _6a03528: https://github.com/level12/keg-mail/commit/6a03528


0.2.2 released 2020-07-22
-------------------------

- Fix bug in LogStatusWebhook view mixin (8a3ffde_)

.. _8a3ffde: https://github.com/level12/keg-mail/commit/8a3ffde


0.2.1 released 2020-07-22
-------------------------

- Add support for Mailgun REST API and message status tracking (b3b4428_)

.. _b3b4428: https://github.com/level12/keg-mail/commit/b3b4428


0.2.0 released 2020-04-14
-------------------------

- Support Python 3.8 (bfbb945_)

.. _bfbb945: https://github.com/level12/keg-mail/commit/bfbb945


0.1.0 - 2017-03-23
------------------

- Initial Release