Anymail: Multi-ESP transactional email for Django
=================================================

..  This README is reused in multiple places:
    * Github: project page, exactly as it appears here
    * Docs: shared-intro section gets included in docs/index.rst
            quickstart section gets included in docs/quickstart.rst
    * PyPI: project page (via setup.py long_description),
            with several edits to freeze it to the specific PyPI release
            (see long_description_from_readme in setup.py)
    You can use docutils 1.0 markup, but *not* any Sphinx additions.

.. default-role:: literal


.. _shared-intro:

.. This shared-intro section is also included in docs/index.rst

Anymail integrates several transactional email service providers (ESPs) into Django,
using a consistent API that makes it (relatively) easy to switch between ESPs.

It currently supports Mailgun and Mandrill. Postmark and SendGrid are coming soon.

.. attention:: **EARLY DEVELOPMENT**

   This project is undergoing rapid development to get to a 1.0 release.
   You should expect frequent, possibly-breaking changes until 1.0 alpha.

   If you are migrating to Anymail from `Djrill <https://github.com/brack3t/Djrill>`_,
   there are `notes on porting <https://anymail.readthedocs.org/en/latest/esps/mandrill/#migrating-from-djrill>`_


Anymail normalizes ESP functionality so it "just works" with Django's
built-in `django.core.mail` package. It includes:

* Support for HTML, attachments, extra headers, and other features of
  `Django's built-in email <https://docs.djangoproject.com/en/stable/topics/email/>`_
* Extensions that make it easy to use extra ESP functionality, like tags, metadata,
  and tracking, using code that's portable between ESPs
* Optional support for ESP delivery status notification via webhooks and Django signals
* Optional support for inbound email

Anymail is released under the BSD license. It is tested against Django 1.8--1.9
(including Python 3 and PyPy).
Djrill uses `semantic versioning <http://semver.org/>`_.

.. END shared-intro

.. image:: https://travis-ci.org/anymail/django-anymail.png?branch=master
       :target: https://travis-ci.org/anymail/django-anymail
       :alt:    build status on Travis-CI


**Resources**

* Full documentation: https://anymail.readthedocs.org/en/latest/
* Package on PyPI: https://pypi.python.org/pypi/django-anymail
* Project on Github: https://github.com/anymail/django-anymail


Anymail 1-2-3
-------------

.. _quickstart:

.. This quickstart section is also included in docs/quickstart.rst

This example uses Mailgun, but you can substitute Postmark or SendGrid
or any other supported ESP where you see "mailgun":

1. Install Anymail from PyPI, including the ESP(s) you want to use:

   .. code-block:: console

        $ pip install anymail[mailgun]  # or anymail[postmark,sendgrid] or ...


2. Edit your project's ``settings.py``:

   .. code-block:: python

        INSTALLED_APPS = (
            ...
            "anymail"
        )

        ANYMAIL = {
            "MAILGUN_API_KEY": "<your Mailgun key>",
        }
        EMAIL_BACKEND = "anymail.backends.mailgun.MailgunBackend"  # or sendgrid.SendGridBackend, or...
        DEFAULT_FROM_EMAIL = "you@example.com"  # if you don't already have this in settings


3. Now the regular `Django email functions <https://docs.djangoproject.com/en/stable/topics/email/>`_
   will send through your chosen ESP:

   .. code-block:: python

        from django.core.mail import send_mail

        send_mail("It works!", "This will get sent through Mailgun",
                  "Anymail Sender <from@example.com>", ["to@example.com"])


   You could send an HTML message, complete with an inline image,
   custom tags and metadata:

   .. code-block:: python

        from django.core.mail import EmailMultiAlternatives
        from anymail.message import attach_inline_image

        msg = EmailMultiAlternatives(
            subject="Please activate your account",
            body="Click to activate your account: http://example.com/activate",
            from_email="Example <admin@example.com>",
            to=["New User <user1@example.com>", "account.manager@example.com"],
            reply_to=["Helpdesk <support@example.com>"])

        # Include an inline image in the html:
        logo_cid = attach_inline_image(msg, open("logo.jpg", "rb").read())
        html = """<img alt="Logo" src="cid:{logo_cid}">
                  <p>Please <a href="http://example.com/activate">activate</a>
                  your account</p>""".format(logo_cid=logo_cid)
        msg.attach_alternative(html, "text/html")

        # Optional Anymail extensions:
        msg.metadata = {"user_id": "8675309", "experiment_variation": 1}
        msg.tags = ["activation", "onboarding"]
        msg.track_clicks = True

        # Send it:
        msg.send()

.. END quickstart


See the `full documentation <https://anymail.readthedocs.org/en/latest/>`_
for more features and options.