Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jwodder/outgoing-mailgun

outgoing extension for Mailgun
https://github.com/jwodder/outgoing-mailgun

available-on-pypi e-mail email mailgun outgoing python

Last synced: 20 days ago
JSON representation

outgoing extension for Mailgun

Awesome Lists containing this project

README 

        
|repostatus| |ci-status| |coverage| |pyversions| |license|



.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg

    :target: https://www.repostatus.org/#active

    :alt: Project Status: Active — The project has reached a stable, usable

          state and is being actively developed.



.. |ci-status| image:: https://github.com/jwodder/outgoing-mailgun/actions/workflows/test.yml/badge.svg

    :target: https://github.com/jwodder/outgoing-mailgun/actions/workflows/test.yml

    :alt: CI Status



.. |coverage| image:: https://codecov.io/gh/jwodder/outgoing-mailgun/branch/master/graph/badge.svg

    :target: https://codecov.io/gh/jwodder/outgoing-mailgun



.. |pyversions| image:: https://img.shields.io/pypi/pyversions/outgoing-mailgun.svg

    :target: https://pypi.org/project/outgoing-mailgun/



.. |license| image:: https://img.shields.io/github/license/jwodder/outgoing-mailgun.svg

    :target: https://opensource.org/licenses/MIT

    :alt: MIT License



`GitHub `_

| `PyPI `_

| `Issues `_

| `Changelog `_



``outgoing-mailgun`` is an extension for outgoing_ that adds the ability to

send e-mails via Mailgun_.  Simply install ``outgoing-mailgun`` alongside

``outgoing``, and you'll be able to specify "mailgun" as a sending method in

your ``outgoing`` configuration.



.. _outgoing: https://github.com/jwodder/outgoing

.. _Mailgun: https://www.mailgun.com



Installation

============

``outgoing-mailgun`` requires Python 3.8 or higher.  Just use `pip

`_ for Python 3 (You have pip, right?) to install

``outgoing-mailgun`` and its dependencies (including ``outgoing``)::



    python3 -m pip install outgoing-mailgun



Configuration

=============



When using "mailgun" as the sending method in an ``outgoing`` configuration,

the following configuration fields are recognized:



``base-url`` : HTTP URL (optional)

    The base URL to use for Mailgun API requests.  This should be either

    ``"https://api.mailgun.net"`` (the default) for domains in Mailgun's US

    region or ``"https://api.eu.mailgun.net"`` for domains in Mailgun's EU

    region.  Trailing slashes on the URL are optional.



``domain`` : string (required)

    The domain name you registered with Mailgun for sending e-mail



``api-key`` : password (required)

    A Mailgun API key for your domain; see |the outgoing documentation on

    passwords|_ for ways to write this field.



    .. |the outgoing documentation on passwords|

       replace:: the ``outgoing`` documentation on passwords

    .. _the outgoing documentation on passwords:

       https://outgoing.readthedocs.io/en/latest/configuration.html#passwords



    When using the ``keyring`` password scheme or another scheme that takes

    optional host/service and username fields, if the service and/or username

    is not supplied in the password specifier, then the service defaults to the

    domain name of the ``base-url`` field, and the username defaults to the

    value of the ``domain`` field.



``tags`` : list of strings (optional)

    A set of tags to apply to sent e-mails



``deliverytime`` : datetime (optional)

    Desired time of delivery for sent e-mails; if no timezone offset is given,

    it is assumed to be in the local system timezone



``dkim`` : boolean (optional)

    Enable/disable DKIM signatures on sent e-mails



``testmode`` : boolean (optional)

    Whether to send in `test mode`_



    .. _test mode: https://documentation.mailgun.com/en/latest/user_manual.html

                   #sending-in-test-mode



``tracking`` : boolean (optional)

    Whether to enable `message tracking`_



    .. _message tracking: https://documentation.mailgun.com/en/latest

                          /user_manual.html#tracking-messages



``tracking-clicks`` : boolean or ``"htmlonly"`` (optional)

    Whether to enable clicks tracking in e-mails



``tracking-opens`` : boolean (optional)

    Whether to enable opens tracking in e-mails



``headers`` : table with string values (optional)

    A collection of custom MIME headers to append to sent e-mails



``variables`` : table with string values (optional)

    A collection of `Mailgun variables`_ to attach to sent e-mails



    .. _Mailgun variables: https://documentation.mailgun.com/en/latest

                           /user_manual.html#attaching-data-to-messages



Example Configuration

=====================



.. code:: toml



    [outgoing]

    method = "mailgun"

    domain = "mydomain.nil"

    api-key = { file = "~/secrets/mailgun.key" }

    dkim = true

    tags = [ "sent-with-outgoing", "my-campaign" ]

    tracking-clicks = "htmlonly"

    headers = { Reply-To = "[email protected]" }

    variables = { sender = "outgoing", foo = "bar" }



Sender-Specific Behavior

========================



The ``MailgunSender`` class provided by this extension is a reentrant__ and

reusable__ context manager, and its ``send()`` method can be called outside of

a context.  In addition, on success, the ``send()`` method returns the message

ID of the newly-sent e-mail (without enclosing angle brackets).



__ https://docs.python.org/3/library/contextlib.html#reentrant-context-managers

__ https://docs.python.org/3/library/contextlib.html#reusable-context-managers