mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 03:41:05 -05:00
fed98b14a8
Simplify install to just `pip install django-anymail`. (Rather than `... django-anymail[mailgun]` All of the ESPs so far require requests, so just move that into the base requirements. (Chances are your Django app already needs requests for some other reason, anyway.) Truly unique ESP dependencies (e.g., boto for AWS-SES) could still use the setup extra features mechanism.
144 lines
4.8 KiB
ReStructuredText
144 lines
4.8 KiB
ReStructuredText
Anymail: Multi-ESP transactional email for Django
|
|
=================================================
|
|
|
|
**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.
|
|
|
|
.. 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.
|
|
GitHub rst supports code-block, but *no other* block directives.
|
|
|
|
|
|
.. 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,
|
|
with a consistent API that lets you use ESP-added features without locking your code
|
|
to a particular ESP.
|
|
|
|
It currently supports Mailgun, Postmark, SendGrid, and Mandrill.
|
|
|
|
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, with code that's portable between ESPs
|
|
* Simplified inline images for HTML email
|
|
|
|
Support is planned for:
|
|
|
|
* Normalized sent-message tracking status notification via webhooks and Django signals
|
|
* Normalized inbound email processing through your ESP
|
|
|
|
Anymail is released under the BSD license. It is extensively tested against Django 1.8--1.9
|
|
(including Python 2.7, Python 3 and PyPy).
|
|
Anymail releases follow `semantic versioning <http://semver.org/>`_.
|
|
|
|
.. END shared-intro
|
|
|
|
.. image:: https://travis-ci.org/anymail/django-anymail.svg?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:
|
|
|
|
.. code-block:: console
|
|
|
|
$ pip install django-anymail
|
|
|
|
|
|
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_file
|
|
|
|
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_file(msg, "/path/to/logo.jpg")
|
|
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.
|