diff --git a/.travis.yml b/.travis.yml index 89ef3cd..05c78da 100644 --- a/.travis.yml +++ b/.travis.yml @@ -26,6 +26,8 @@ cache: install: - pip install --upgrade setuptools pip - pip install $DJANGO - - pip install . + # For now, install all ESPs and test at once + # (in future, might want to matrix ESPs to test cross-dependencies) + - pip install .[mailgun,mandrill,postmark,sendgrid,sparkpost] - pip list script: python setup.py test diff --git a/README.rst b/README.rst index 404ffb5..5ea21a5 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,5 @@ -Anymail: Django email backends for Mailgun, Postmark, SendGrid and more -======================================================================= +Anymail: Django email backends for Mailgun, Postmark, SendGrid, SparkPost and more +================================================================================== **EARLY DEVELOPMENT** @@ -30,7 +30,7 @@ Anymail integrates several transactional email service providers (ESPs) into Dja with a consistent API that lets you use ESP-added features without locking your code to a particular ESP. -It currently fully supports Mailgun, Postmark, and SendGrid, +It currently fully supports Mailgun, Postmark, SendGrid, and SparkPost, and has limited support for Mandrill. Anymail normalizes ESP functionality so it "just works" with Django's @@ -78,13 +78,16 @@ Anymail 1-2-3 .. 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": +or SparkPost or any other supported ESP where you see "mailgun": 1. Install Anymail from PyPI: .. code-block:: console - $ pip install django-anymail + $ pip install django-anymail[mailgun] + + (The `[mailgun]` part installs any additional packages needed for that ESP. + Mailgun doesn't have any, but some other ESPs do.) 2. Edit your project's ``settings.py``: diff --git a/anymail/backends/sparkpost.py b/anymail/backends/sparkpost.py new file mode 100644 index 0000000..ebaffa5 --- /dev/null +++ b/anymail/backends/sparkpost.py @@ -0,0 +1,190 @@ +from __future__ import absolute_import # we want the sparkpost package, not our own module + +from .base import AnymailBaseBackend, BasePayload +from ..exceptions import AnymailAPIError, AnymailImproperlyInstalled, AnymailConfigurationError +from ..message import AnymailRecipientStatus +from ..utils import get_anymail_setting + +try: + from sparkpost import SparkPost, SparkPostException +except ImportError: + raise AnymailImproperlyInstalled(missing_package='sparkpost', backend='sparkpost') + + +class SparkPostBackend(AnymailBaseBackend): + """ + SparkPost Email Backend (using python-sparkpost client) + """ + + def __init__(self, **kwargs): + """Init options from Django settings""" + super(SparkPostBackend, self).__init__(**kwargs) + # SPARKPOST_API_KEY is optional - library reads from env by default + self.api_key = get_anymail_setting('api_key', esp_name=self.esp_name, + kwargs=kwargs, allow_bare=True, default=None) + try: + self.sp = SparkPost(self.api_key) # SparkPost API instance + except SparkPostException as err: + # This is almost certainly a missing API key + raise AnymailConfigurationError( + "Error initializing SparkPost: %s\n" + "You may need to set ANYMAIL = {'SPARKPOST_API_KEY': ...} " + "or ANYMAIL_SPARKPOST_API_KEY in your Django settings, " + "or SPARKPOST_API_KEY in your environment." % str(err) + ) + + # Note: SparkPost python API doesn't expose requests session sharing + # (so there's no need to implement open/close connection management here) + + def build_message_payload(self, message, defaults): + return SparkPostPayload(message, defaults, self) + + def post_to_esp(self, payload, message): + params = payload.get_api_params() + try: + response = self.sp.transmissions.send(**params) + except SparkPostException as err: + raise AnymailAPIError( + str(err), backend=self, email_message=message, payload=payload, + response=getattr(err, 'response', None), # SparkPostAPIException requests.Response + status_code=getattr(err, 'status', None), # SparkPostAPIException HTTP status_code + ) + return response + + def parse_recipient_status(self, response, payload, message): + try: + accepted = response['total_accepted_recipients'] + rejected = response['total_rejected_recipients'] + transmission_id = response['id'] + except (KeyError, TypeError) as err: + raise AnymailAPIError( + "%s in SparkPost.transmissions.send result %r" % (str(err), response), + backend=self, email_message=message, payload=payload, + ) + + # SparkPost doesn't (yet*) tell us *which* recipients were accepted or rejected. + # (* looks like undocumented 'rcpt_to_errors' might provide this info.) + # If all are one or the other, we can report a specific status; + # else just report 'unknown' for all recipients. + recipient_count = len(payload.all_recipients) + if accepted == recipient_count and rejected == 0: + status = 'queued' + elif rejected == recipient_count and accepted == 0: + status = 'rejected' + else: # mixed results, or wrong total + status = 'unknown' + recipient_status = AnymailRecipientStatus(message_id=transmission_id, status=status) + return {recipient.email: recipient_status for recipient in payload.all_recipients} + + +class SparkPostPayload(BasePayload): + def init_payload(self): + self.params = {} + self.all_recipients = [] + self.to_emails = [] + self.merge_data = {} + + def get_api_params(self): + # Compose recipients param from to_emails and merge_data (if any) + recipients = [] + for email in self.to_emails: + rcpt = {'address': {'email': email.email}} + if email.name: + rcpt['address']['name'] = email.name + try: + rcpt['substitution_data'] = self.merge_data[email.email] + except KeyError: + pass # no merge_data or none for this recipient + recipients.append(rcpt) + if recipients: + self.params['recipients'] = recipients + + return self.params + + def set_from_email(self, email): + self.params['from_email'] = email.address + + def set_to(self, emails): + if emails: + self.to_emails = emails # bound to params['recipients'] in get_api_params + self.all_recipients += emails + + def set_cc(self, emails): + if emails: + self.params['cc'] = [email.address for email in emails] + self.all_recipients += emails + + def set_bcc(self, emails): + if emails: + self.params['bcc'] = [email.address for email in emails] + self.all_recipients += emails + + def set_subject(self, subject): + self.params['subject'] = subject + + def set_reply_to(self, emails): + if emails: + # reply_to is only documented as a single email, but this seems to work: + self.params['reply_to'] = ', '.join([email.address for email in emails]) + + def set_extra_headers(self, headers): + if headers: + self.params['custom_headers'] = headers + + def set_text_body(self, body): + self.params['text'] = body + + def set_html_body(self, body): + if 'html' in self.params: + # second html body could show up through multiple alternatives, or html body + alternative + self.unsupported_feature("multiple html parts") + self.params['html'] = body + + def add_attachment(self, attachment): + if attachment.inline: + param = 'inline_images' + name = attachment.cid + else: + param = 'attachments' + name = attachment.name or '' + + self.params.setdefault(param, []).append({ + 'type': attachment.mimetype, + 'name': name, + 'data': attachment.b64content}) + + # Anymail-specific payload construction + def set_metadata(self, metadata): + self.params['metadata'] = metadata + + def set_send_at(self, send_at): + try: + self.params['start_time'] = send_at.replace(microsecond=0).isoformat() + except (AttributeError, TypeError): + self.params['start_time'] = send_at # assume user already formatted + + def set_tags(self, tags): + if len(tags) > 0: + self.params['campaign'] = tags[0] + if len(tags) > 1: + self.unsupported_feature('multiple tags (%r)' % tags) + + def set_track_clicks(self, track_clicks): + self.params['track_clicks'] = track_clicks + + def set_track_opens(self, track_opens): + self.params['track_opens'] = track_opens + + def set_template_id(self, template_id): + # 'template' transmissions.send param becomes 'template_id' in API json 'content' + self.params['template'] = template_id + + def set_merge_data(self, merge_data): + self.merge_data = merge_data # merged into params['recipients'] in get_api_params + + def set_merge_global_data(self, merge_global_data): + self.params['substitution_data'] = merge_global_data + + # ESP-specific payload construction + def set_esp_extra(self, extra): + self.params.update(extra) diff --git a/anymail/urls.py b/anymail/urls.py index 3af0c89..5a22094 100644 --- a/anymail/urls.py +++ b/anymail/urls.py @@ -4,6 +4,7 @@ from .webhooks.mailgun import MailgunTrackingWebhookView from .webhooks.mandrill import MandrillTrackingWebhookView from .webhooks.postmark import PostmarkTrackingWebhookView from .webhooks.sendgrid import SendGridTrackingWebhookView +from .webhooks.sparkpost import SparkPostTrackingWebhookView app_name = 'anymail' @@ -12,4 +13,5 @@ urlpatterns = [ url(r'^mandrill/tracking/$', MandrillTrackingWebhookView.as_view(), name='mandrill_tracking_webhook'), url(r'^postmark/tracking/$', PostmarkTrackingWebhookView.as_view(), name='postmark_tracking_webhook'), url(r'^sendgrid/tracking/$', SendGridTrackingWebhookView.as_view(), name='sendgrid_tracking_webhook'), + url(r'^sparkpost/tracking/$', SparkPostTrackingWebhookView.as_view(), name='sparkpost_tracking_webhook'), ] diff --git a/anymail/webhooks/sparkpost.py b/anymail/webhooks/sparkpost.py new file mode 100644 index 0000000..aeb3b37 --- /dev/null +++ b/anymail/webhooks/sparkpost.py @@ -0,0 +1,136 @@ +import json +from datetime import datetime + +from django.utils.timezone import utc + +from .base import AnymailBaseWebhookView +from ..exceptions import AnymailConfigurationError +from ..signals import tracking, AnymailTrackingEvent, EventType, RejectReason + + +class SparkPostBaseWebhookView(AnymailBaseWebhookView): + """Base view class for SparkPost webhooks""" + + def parse_events(self, request): + raw_events = json.loads(request.body.decode('utf-8')) + unwrapped_events = [self.unwrap_event(raw_event) for raw_event in raw_events] + return [ + self.esp_to_anymail_event(event_class, event, raw_event) + for (event_class, event, raw_event) in unwrapped_events + if event is not None # filter out empty "ping" events + ] + + def unwrap_event(self, raw_event): + """Unwraps SparkPost event structure, and returns event_class, event, raw_event + + raw_event is of form {'msys': {event_class: {...event...}}} + + Can return None, None, raw_event for SparkPost "ping" raw_event={'msys': {}} + """ + event_classes = raw_event['msys'].keys() + try: + (event_class,) = event_classes + event = raw_event['msys'][event_class] + except ValueError: # too many/not enough event_classes to unpack + if len(event_classes) == 0: + # Empty event (SparkPost sometimes sends as a "ping") + event_class = event = None + else: + raise TypeError("Invalid SparkPost webhook event has multiple event classes: %r" % raw_event) + return event_class, event, raw_event + + def esp_to_anymail_event(self, event_class, event, raw_event): + raise NotImplementedError() + + +class SparkPostTrackingWebhookView(SparkPostBaseWebhookView): + """Handler for SparkPost message, engagement, and generation event webhooks""" + + signal = tracking + + event_types = { + # Map SparkPost event.type: Anymail normalized type + 'bounce': EventType.BOUNCED, + 'delivery': EventType.DELIVERED, + 'injection': EventType.QUEUED, + 'spam_complaint': EventType.COMPLAINED, + 'out_of_band': EventType.BOUNCED, + 'policy_rejection': EventType.REJECTED, + 'delay': EventType.DEFERRED, + 'click': EventType.CLICKED, + 'open': EventType.OPENED, + 'generation_failure': EventType.FAILED, + 'generation_rejection': EventType.REJECTED, + 'list_unsubscribe': EventType.UNSUBSCRIBED, + 'link_unsubscribe': EventType.UNSUBSCRIBED, + } + + reject_reasons = { + # Map SparkPost event.bounce_class: Anymail normalized reject reason. + # Can also supply (RejectReason, EventType) for bounce_class that affects our event_type. + # https://support.sparkpost.com/customer/portal/articles/1929896 + '1': RejectReason.OTHER, # Undetermined (response text could not be identified) + '10': RejectReason.INVALID, # Invalid Recipient + '20': RejectReason.BOUNCED, # Soft Bounce + '21': RejectReason.BOUNCED, # DNS Failure + '22': RejectReason.BOUNCED, # Mailbox Full + '23': RejectReason.BOUNCED, # Too Large + '24': RejectReason.TIMED_OUT, # Timeout + '25': RejectReason.BLOCKED, # Admin Failure (configured policies) + '30': RejectReason.BOUNCED, # Generic Bounce: No RCPT + '40': RejectReason.BOUNCED, # Generic Bounce: unspecified reasons + '50': RejectReason.BLOCKED, # Mail Block (by the receiver) + '51': RejectReason.SPAM, # Spam Block (by the receiver) + '52': RejectReason.SPAM, # Spam Content (by the receiver) + '53': RejectReason.OTHER, # Prohibited Attachment (by the receiver) + '54': RejectReason.BLOCKED, # Relaying Denied (by the receiver) + '60': (RejectReason.OTHER, EventType.AUTORESPONDED), # Auto-Reply/vacation + '70': RejectReason.BOUNCED, # Transient Failure + '80': (RejectReason.OTHER, EventType.SUBSCRIBED), # Subscribe + '90': (RejectReason.UNSUBSCRIBED, EventType.UNSUBSCRIBED), # Unsubscribe + '100': (RejectReason.OTHER, EventType.AUTORESPONDED), # Challenge-Response + } + + def esp_to_anymail_event(self, event_class, event, raw_event): + if event_class == 'relay_event': + # This is an inbound event + raise AnymailConfigurationError( + "You seem to have set SparkPost's *inbound* relay webhook URL " + "to Anymail's SparkPost *tracking* webhook URL.") + + event_type = self.event_types.get(event['type'], EventType.UNKNOWN) + try: + timestamp = datetime.fromtimestamp(int(event['timestamp']), tz=utc) + except (KeyError, TypeError, ValueError): + timestamp = None + + try: + tag = event['campaign_id'] # not 'rcpt_tags' -- those don't come from sending a message + tags = [tag] if tag else None + except KeyError: + tags = None + + try: + reject_reason = self.reject_reasons.get(event['bounce_class'], RejectReason.OTHER) + try: # unpack (RejectReason, EventType) for reasons that change our event type + reject_reason, event_type = reject_reason + except ValueError: + pass + except KeyError: + reject_reason = None # no bounce_class + + return AnymailTrackingEvent( + event_type=event_type, + timestamp=timestamp, + message_id=event.get('transmission_id', None), # not 'message_id' -- see SparkPost backend + event_id=event.get('event_id', None), + recipient=event.get('raw_rcpt_to', None), # preserves email case (vs. 'rcpt_to') + reject_reason=reject_reason, + mta_response=event.get('raw_reason', None), + # description=???, + tags=tags, + metadata=event.get('rcpt_meta', None) or None, # message + recipient metadata + click_url=event.get('target_link_url', None), + user_agent=event.get('user_agent', None), + esp_event=raw_event, + ) diff --git a/docs/esps/index.rst b/docs/esps/index.rst index 8cdf7d8..dbb4e64 100644 --- a/docs/esps/index.rst +++ b/docs/esps/index.rst @@ -16,6 +16,7 @@ and notes about any quirks or limitations: mandrill postmark sendgrid + sparkpost Anymail feature support @@ -25,28 +26,28 @@ The table below summarizes the Anymail features supported for each ESP. .. currentmodule:: anymail.message -============================================ ========== ========== ========== ========== -Email Service Provider |Mailgun| |Mandrill| |Postmark| |SendGrid| -============================================ ========== ========== ========== ========== +============================================ ========== ========== ========== ========== =========== +Email Service Provider |Mailgun| |Mandrill| |Postmark| |SendGrid| |SparkPost| +============================================ ========== ========== ========== ========== =========== .. rubric:: :ref:`Anymail send options ` --------------------------------------------------------------------------------------------- -:attr:`~AnymailMessage.metadata` Yes Yes No Yes -:attr:`~AnymailMessage.send_at` Yes Yes No Yes -:attr:`~AnymailMessage.tags` Yes Yes Max 1 tag Yes -:attr:`~AnymailMessage.track_clicks` Yes Yes No Yes -:attr:`~AnymailMessage.track_opens` Yes Yes Yes Yes +--------------------------------------------------------------------------------------------------------- +:attr:`~AnymailMessage.metadata` Yes Yes No Yes Yes +:attr:`~AnymailMessage.send_at` Yes Yes No Yes Yes +:attr:`~AnymailMessage.tags` Yes Yes Max 1 tag Yes Max 1 tag +:attr:`~AnymailMessage.track_clicks` Yes Yes No Yes Yes +:attr:`~AnymailMessage.track_opens` Yes Yes Yes Yes Yes .. rubric:: :ref:`templates-and-merge` --------------------------------------------------------------------------------------------- -:attr:`~AnymailMessage.template_id` No Yes Yes Yes -:attr:`~AnymailMessage.merge_data` Yes Yes No Yes -:attr:`~AnymailMessage.merge_global_data` (emulated) Yes Yes Yes +--------------------------------------------------------------------------------------------------------- +:attr:`~AnymailMessage.template_id` No Yes Yes Yes Yes +:attr:`~AnymailMessage.merge_data` Yes Yes No Yes Yes +:attr:`~AnymailMessage.merge_global_data` (emulated) Yes Yes Yes Yes .. rubric:: :ref:`Status ` and :ref:`event tracking ` --------------------------------------------------------------------------------------------- -:attr:`~AnymailMessage.anymail_status` Yes Yes Yes Yes -|AnymailTrackingEvent| from webhooks Yes Yes Yes Yes -============================================ ========== ========== ========== ========== +--------------------------------------------------------------------------------------------------------- +:attr:`~AnymailMessage.anymail_status` Yes Yes Yes Yes Yes +|AnymailTrackingEvent| from webhooks Yes Yes Yes Yes Yes +============================================ ========== ========== ========== ========== =========== .. .. rubric:: :ref:`inbound` @@ -62,6 +63,7 @@ meaningless. (And even specific features don't matter if you don't plan to use t .. |Mandrill| replace:: :ref:`mandrill-backend` .. |Postmark| replace:: :ref:`postmark-backend` .. |SendGrid| replace:: :ref:`sendgrid-backend` +.. |SparkPost| replace:: :ref:`sparkpost-backend` .. |AnymailTrackingEvent| replace:: :class:`~anymail.signals.AnymailTrackingEvent` diff --git a/docs/esps/sparkpost.rst b/docs/esps/sparkpost.rst new file mode 100644 index 0000000..57166e9 --- /dev/null +++ b/docs/esps/sparkpost.rst @@ -0,0 +1,221 @@ +.. _sparkpost-backend: + +SparkPost +========= + +Anymail integrates with the `SparkPost`_ email service, using their +`python-sparkpost`_ API client. + +.. _SparkPost: https://www.sparkpost.com/ +.. _python-sparkpost: https://pypi.python.org/pypi/sparkpost + + +Installation +------------ + +You must ensure the `sparkpost` package is installed to use Anymail's SparkPost +backend. Either include the "sparkpost" option when you install Anymail: + + .. code-block:: console + + $ pip install django-anymail[sparkpost] + +or separately run `pip install sparkpost`. + + +Settings +-------- + + +.. rubric:: EMAIL_BACKEND + +To use Anymail's SparkPost backend, set: + + .. code-block:: python + + EMAIL_BACKEND = "anymail.backends.sparkpost.SparkPostBackend" + +in your settings.py. (Watch your capitalization: SparkPost spells +their name with an inner capital "P", so Anymail does too.) + + +.. setting:: ANYMAIL_SPARKPOST_API_KEY + +.. rubric:: SPARKPOST_API_KEY + +A SparkPost API key with at least the "Transmissions: Read/Write" permission. +(Manage API keys in your `SparkPost account API keys`_.) + +This setting is optional; if not provided, the SparkPost API client will attempt +to read your API key from the `SPARKPOST_API_KEY` environment variable. + + .. code-block:: python + + ANYMAIL = { + ... + "SPARKPOST_API_KEY": "", + } + +Anymail will also look for ``SPARKPOST_API_KEY`` at the +root of the settings file if neither ``ANYMAIL["SPARKPOST_API_KEY"]`` +nor ``ANYMAIL_SPARKPOST_API_KEY`` is set. + +.. _SparkPost account API keys: https://app.sparkpost.com/account/credentials + + +.. _sparkpost-esp-extra: + +esp_extra support +----------------- + +To use SparkPost features not directly supported by Anymail, you can +set a message's :attr:`~anymail.message.AnymailMessage.esp_extra` to +a `dict` of parameters for python-sparkpost's `transmissions.send method`_. +Any keys in your :attr:`esp_extra` dict will override Anymail's normal +values for that parameter. + +Example: + + .. code-block:: python + + message.esp_extra = { + 'transactional': True, # treat as transactional for unsubscribe and suppression + 'description': "Marketing test-run for new templates", + 'use_draft_template': True, + } + + +(You can also set `"esp_extra"` in Anymail's :ref:`global send defaults ` +to apply it to all messages.) + +.. _transmissions.send method: + https://python-sparkpost.readthedocs.io/en/latest/api/transmissions.html#sparkpost.transmissions.Transmissions.send + + + +Limitations and quirks +---------------------- + +.. _sparkpost-message-id: + +**Anymail's `message_id` is SparkPost's `transmission_id`** + The :attr:`~anymail.message.AnymailStatus.message_id` Anymail sets + on a message's :attr:`~anymail.message.AnymailMessage.anymail_status` + and in normalized webhook :class:`~anymail.signals.AnymailTrackingEvent` + data is actually what SparkPost calls "transmission_id". + + Like Anymail's message_id for other ESPs, SparkPost's transmission_id + (together with the recipient email address), uniquely identifies a + particular message instance in tracking events. + + (The transmission_id is the only unique identifier available when you + send your message. SparkPost also has something called "message_id", but + that doesn't get assigned until after the send API call has completed.) + + If you are working exclusively with Anymail's normalized message status + and webhook events, the distinction won't matter: you can consistently + use Anymail's `message_id`. But if you are also working with raw webhook + esp_event data or SparkPost's events API, be sure to think "transmission_id" + wherever you're speaking to SparkPost. + +**Single tag** + Anymail uses SparkPost's "campaign_id" to implement message tagging. + SparkPost only allows a single campaign_id per message. If your message has + two or more :attr:`~anymail.message.AnymailMessage.tags`, you'll get an + :exc:`~anymail.exceptions.AnymailUnsupportedFeature` error---or + if you've enabled :setting:`ANYMAIL_IGNORE_UNSUPPORTED_FEATURES`, + Anymail will use only the first tag. + + (SparkPost's "recipient tags" are not available for tagging *messages*. + They're associated with individual *addresses* in stored recipient lists.) + + +.. _sparkpost-templates: + +Batch sending/merge and ESP templates +------------------------------------- + +SparkPost offers both :ref:`ESP stored templates ` +and :ref:`batch sending ` with per-recipient merge data. + +You can use a SparkPost stored template by setting a message's +:attr:`~anymail.message.AnymailMessage.template_id` to the +template's unique id. Alternatively, you can refer to merge fields +directly in an EmailMessage---the message itself is used as an +on-the-fly template. + +In either case, supply the merge data values with Anymail's +normalized :attr:`~anymail.message.AnymailMessage.merge_data` +and :attr:`~anymail.message.AnymailMessage.merge_global_data` +message attributes. + + .. code-block:: python + + message = EmailMessage( + ... + to=["alice@example.com", "Bob "] + ) + message.template_id = "11806290401558530" # SparkPost id + message.merge_data = { + 'alice@example.com': {'name': "Alice", 'order_no': "12345"}, + 'bob@example.com': {'name': "Bob", 'order_no': "54321"}, + } + message.merge_global_data = { + 'ship_date': "May 15", + # Can use SparkPost's special "dynamic" keys for nested substitutions (see notes): + 'dynamic_html': { + 'status_html': "Status", + }, + 'dynamic_plain': { + 'status_plain': "Status: https://example.com/order/{{order_no}}", + }, + } + + +See `SparkPost's substitutions reference`_ for more information on templates and +batch send with SparkPost. If you need the special `"dynamic" keys for nested substitutions`_, +provide them in Anymail's :attr:`~anymail.message.AnymailMessage.merge_global_data` +as shown in the example above. And if you want `use_draft_template` behavior, specify that +in :ref:`esp_extra `. + + +.. _SparkPost's substitutions reference: + https://developers.sparkpost.com/api/substitutions-reference + +.. _"dynamic" keys for nested substitutions: + https://developers.sparkpost.com/api/substitutions-reference#header-links-and-substitution-expressions-within-substitution-values + + +.. _sparkpost-webhooks: + +Status tracking webhooks +------------------------ + +If you are using Anymail's normalized :ref:`status tracking `, set up the +webhook in your `SparkPost account settings under "Webhooks"`_: + +* Target URL: :samp:`https://{yoursite.example.com}/anymail/sparkpost/tracking/` +* Authentication: choose "Basic Auth." For username and password enter the two halves of the + *random:random* shared secret you created for your :setting:`ANYMAIL_WEBHOOK_AUTHORIZATION` + Django setting. (Anymail doesn't support OAuth webhook auth.) +* Events: click "Select" and then *clear* the checkbox for "Relay Events" category (which is for + inbound email). You can leave all the other categories of events checked, or disable + any you aren't interested in tracking. + +SparkPost will report these Anymail :attr:`~anymail.signals.AnymailTrackingEvent.event_type`\s: +queued, rejected, bounced, deferred, delivered, opened, clicked, complained, unsubscribed, +subscribed. + +The event's :attr:`~anymail.signals.AnymailTrackingEvent.esp_event` field will be +a single, raw `SparkPost event`_. (Although SparkPost calls webhooks with batches of events, +Anymail will invoke your signal receiver separately for each event in the batch.) +The esp_event is the raw, `wrapped json event structure`_ as provided by SparkPost: +`{'msys': {'': {......}}}`. + + +.. _SparkPost account settings under "Webhooks": + https://app.sparkpost.com/account/webhooks +.. _SparkPost event: + https://support.sparkpost.com/customer/portal/articles/1976204-webhook-event-reference +.. _wrapped json event structure: + https://support.sparkpost.com/customer/en/portal/articles/2311698-comparing-webhook-and-message-event-data diff --git a/docs/installation.rst b/docs/installation.rst index d276f64..7d14cee 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -10,10 +10,14 @@ It's easiest to install Anymail from PyPI using pip. .. code-block:: console - $ pip install django-anymail + $ pip install django-anymail[sendgrid,sparkpost] -If you don't want to use pip, you'll also need to install Anymail's -dependencies (requests and six). +The `[sendgrid,sparkpost]` part of that command tells pip you also +want to install additional packages required for those ESPs. +You can give one or more comma-separated, lowercase ESP names. +(Most ESPs don't have additional requirements, so you can often +just skip this. Or change your mind later. Anymail will let you know +if there are any missing dependencies when you try to use it.) .. _backend-configuration: diff --git a/setup.py b/setup.py index 74594c2..38035d5 100644 --- a/setup.py +++ b/setup.py @@ -43,6 +43,7 @@ setup( "mandrill": [], "postmark": [], "sendgrid": [], + "sparkpost": ["sparkpost"], }, include_package_data=True, test_suite="runtests.runtests", diff --git a/tests/test_sparkpost_backend.py b/tests/test_sparkpost_backend.py new file mode 100644 index 0000000..4cfd356 --- /dev/null +++ b/tests/test_sparkpost_backend.py @@ -0,0 +1,588 @@ +# -*- coding: utf-8 -*- + +from datetime import datetime, date +from email.mime.base import MIMEBase +from email.mime.image import MIMEImage + +import requests +import six +from django.core import mail +from django.test import SimpleTestCase +from django.test.utils import override_settings +from django.utils.timezone import get_fixed_timezone, override as override_current_timezone, utc +from mock import patch +from sparkpost.exceptions import SparkPostAPIException + +from anymail.exceptions import (AnymailAPIError, AnymailUnsupportedFeature, AnymailRecipientsRefused, + AnymailConfigurationError) +from anymail.message import attach_inline_image_file + +try: + # noinspection PyUnresolvedReferences + from test.support import EnvironmentVarGuard # python3 +except ImportError: + # noinspection PyUnresolvedReferences + from test.test_support import EnvironmentVarGuard # python2 + +from .utils import AnymailTestMixin, decode_att, SAMPLE_IMAGE_FILENAME, sample_image_path, sample_image_content + + +@override_settings(EMAIL_BACKEND='anymail.backends.sparkpost.SparkPostBackend', + ANYMAIL={'SPARKPOST_API_KEY': 'test_api_key'}) +class SparkPostBackendMockAPITestCase(SimpleTestCase, AnymailTestMixin): + """TestCase that uses SparkPostEmailBackend with a mocked transmissions.send API""" + + def setUp(self): + super(SparkPostBackendMockAPITestCase, self).setUp() + self.patch_send = patch('sparkpost.Transmissions.send', autospec=True) + self.mock_send = self.patch_send.start() + self.addCleanup(self.patch_send.stop) + self.set_mock_response() + + # Simple message useful for many tests + self.message = mail.EmailMultiAlternatives('Subject', 'Text Body', + 'from@example.com', ['to@example.com']) + + def set_mock_response(self, accepted=1, rejected=0, raw=None): + # SparkPost.transmissions.send returns the parsed 'result' field + # from the transmissions/send JSON response + self.mock_send.return_value = raw or { + "id": "12345678901234567890", + "total_accepted_recipients": accepted, + "total_rejected_recipients": rejected, + } + return self.mock_send.return_value + + def set_mock_failure(self, status_code=400, raw=b'{"errors":[{"message":"test error"}]}', encoding='utf-8'): + # Need to build a real(-ish) requests.Response for SparkPostAPIException + response = requests.Response() + response.status_code = status_code + response.encoding = encoding + response.raw = six.BytesIO(raw) + response.url = "/mock/send" + self.mock_send.side_effect = SparkPostAPIException(response) + + def get_send_params(self): + """Returns kwargs params passed to the mock send API. + + Fails test if API wasn't called. + """ + if self.mock_send.call_args is None: + raise AssertionError("API was not called") + (args, kwargs) = self.mock_send.call_args + return kwargs + + def get_send_api_key(self): + """Returns api_key on SparkPost api object used for mock send + + Fails test if API wasn't called + """ + if self.mock_send.call_args is None: + raise AssertionError("API was not called") + (args, kwargs) = self.mock_send.call_args + mock_self = args[0] + return mock_self.api_key + + def assert_esp_not_called(self, msg=None): + if self.mock_send.called: + raise AssertionError(msg or "ESP API was called and shouldn't have been") + + +class SparkPostBackendStandardEmailTests(SparkPostBackendMockAPITestCase): + """Test backend support for Django standard email features""" + + def test_send_mail(self): + """Test basic API for simple send""" + mail.send_mail('Subject here', 'Here is the message.', + 'from@example.com', ['to@example.com'], fail_silently=False) + params = self.get_send_params() + self.assertEqual(params['subject'], "Subject here") + self.assertEqual(params['text'], "Here is the message.") + self.assertEqual(params['from_email'], "from@example.com") + self.assertEqual(params['recipients'], [{'address': {'email': "to@example.com"}}]) + + self.assertEqual(self.get_send_api_key(), 'test_api_key') + + def test_name_addr(self): + """Make sure RFC2822 name-addr format (with display-name) is allowed + + (Test both sender and recipient addresses) + """ + self.set_mock_response(accepted=6) + msg = mail.EmailMessage( + 'Subject', 'Message', 'From Name ', + ['Recipient #1 ', 'to2@example.com'], + cc=['Carbon Copy ', 'cc2@example.com'], + bcc=['Blind Copy ', 'bcc2@example.com']) + msg.send() + params = self.get_send_params() + self.assertEqual(params['from_email'], "From Name ") + # We pre-parse the to-field emails (merge_data also gets attached there): + self.assertEqual(params['recipients'], [ + {'address': {'email': 'to1@example.com', 'name': 'Recipient #1'}}, + {'address': {'email': 'to2@example.com'}} + ]) + # We let python-sparkpost parse the other email fields: + self.assertEqual(params['cc'], ['Carbon Copy ', 'cc2@example.com']) + self.assertEqual(params['bcc'], ['Blind Copy ', 'bcc2@example.com']) + + def test_email_message(self): + self.set_mock_response(accepted=6) + email = mail.EmailMessage( + 'Subject', 'Body goes here', 'from@example.com', + ['to1@example.com', 'Also To '], + bcc=['bcc1@example.com', 'Also BCC '], + cc=['cc1@example.com', 'Also CC '], + headers={'Reply-To': 'another@example.com', + 'X-MyHeader': 'my value', + 'Message-ID': 'mycustommsgid@example.com'}) + email.send() + params = self.get_send_params() + self.assertEqual(params['subject'], "Subject") + self.assertEqual(params['text'], "Body goes here") + self.assertEqual(params['from_email'], "from@example.com") + self.assertEqual(params['recipients'], [ + {'address': {'email': 'to1@example.com'}}, + {'address': {'email': 'to2@example.com', 'name': 'Also To'}} + ]) + self.assertEqual(params['bcc'], ['bcc1@example.com', 'Also BCC ']) + self.assertEqual(params['cc'], ['cc1@example.com', 'Also CC ']) + self.assertEqual(params['custom_headers'], { + 'Reply-To': 'another@example.com', + 'X-MyHeader': 'my value', + 'Message-ID': 'mycustommsgid@example.com'}) + + def test_html_message(self): + text_content = 'This is an important message.' + html_content = '

This is an important message.

' + email = mail.EmailMultiAlternatives('Subject', text_content, + 'from@example.com', ['to@example.com']) + email.attach_alternative(html_content, "text/html") + email.send() + params = self.get_send_params() + self.assertEqual(params['text'], text_content) + self.assertEqual(params['html'], html_content) + # Don't accidentally send the html part as an attachment: + self.assertNotIn('attachments', params) + + def test_html_only_message(self): + html_content = '

This is an important message.

' + email = mail.EmailMessage('Subject', html_content, 'from@example.com', ['to@example.com']) + email.content_subtype = "html" # Main content is now text/html + email.send() + params = self.get_send_params() + self.assertNotIn('text', params) + self.assertEqual(params['html'], html_content) + + def test_reply_to(self): + email = mail.EmailMessage('Subject', 'Body goes here', 'from@example.com', ['to1@example.com'], + reply_to=['reply@example.com', 'Other '], + headers={'X-Other': 'Keep'}) + email.send() + params = self.get_send_params() + self.assertEqual(params['reply_to'], 'reply@example.com, Other ') + self.assertEqual(params['custom_headers'], {'X-Other': 'Keep'}) # don't lose other headers + + def test_attachments(self): + text_content = "* Item one\n* Item two\n* Item three" + self.message.attach(filename="test.txt", content=text_content, mimetype="text/plain") + + # Should guess mimetype if not provided... + png_content = b"PNG\xb4 pretend this is the contents of a png file" + self.message.attach(filename="test.png", content=png_content) + + # Should work with a MIMEBase object (also tests no filename)... + pdf_content = b"PDF\xb4 pretend this is valid pdf params" + mimeattachment = MIMEBase('application', 'pdf') + mimeattachment.set_payload(pdf_content) + self.message.attach(mimeattachment) + + self.message.send() + params = self.get_send_params() + attachments = params['attachments'] + self.assertEqual(len(attachments), 3) + self.assertEqual(attachments[0]['type'], 'text/plain') + self.assertEqual(attachments[0]['name'], 'test.txt') + self.assertEqual(decode_att(attachments[0]['data']).decode('ascii'), text_content) + self.assertEqual(attachments[1]['type'], 'image/png') # inferred from filename + self.assertEqual(attachments[1]['name'], 'test.png') + self.assertEqual(decode_att(attachments[1]['data']), png_content) + self.assertEqual(attachments[2]['type'], 'application/pdf') + self.assertEqual(attachments[2]['name'], '') # none + self.assertEqual(decode_att(attachments[2]['data']), pdf_content) + # Make sure the image attachment is not treated as embedded: + self.assertNotIn('inline_images', params) + + def test_unicode_attachment_correctly_decoded(self): + # Slight modification from the Django unicode docs: + # http://django.readthedocs.org/en/latest/ref/unicode.html#email + self.message.attach("Une pièce jointe.html", '

\u2019

', mimetype='text/html') + self.message.send() + params = self.get_send_params() + attachments = params['attachments'] + self.assertEqual(len(attachments), 1) + + def test_embedded_images(self): + image_filename = SAMPLE_IMAGE_FILENAME + image_path = sample_image_path(image_filename) + image_data = sample_image_content(image_filename) + + cid = attach_inline_image_file(self.message, image_path) + html_content = '

This has an inline image.

' % cid + self.message.attach_alternative(html_content, "text/html") + + self.message.send() + params = self.get_send_params() + self.assertEqual(params['html'], html_content) + + self.assertEqual(len(params['inline_images']), 1) + self.assertEqual(params['inline_images'][0]["type"], "image/png") + self.assertEqual(params['inline_images'][0]["name"], cid) + self.assertEqual(decode_att(params['inline_images'][0]["data"]), image_data) + # Make sure neither the html nor the inline image is treated as an attachment: + self.assertNotIn('attachments', params) + + def test_attached_images(self): + image_filename = SAMPLE_IMAGE_FILENAME + image_path = sample_image_path(image_filename) + image_data = sample_image_content(image_filename) + + self.message.attach_file(image_path) # option 1: attach as a file + + image = MIMEImage(image_data) # option 2: construct the MIMEImage and attach it directly + self.message.attach(image) + + self.message.send() + params = self.get_send_params() + attachments = params['attachments'] + self.assertEqual(len(attachments), 2) + self.assertEqual(attachments[0]["type"], "image/png") + self.assertEqual(attachments[0]["name"], image_filename) + self.assertEqual(decode_att(attachments[0]["data"]), image_data) + self.assertEqual(attachments[1]["type"], "image/png") + self.assertEqual(attachments[1]["name"], "") # unknown -- not attached as file + self.assertEqual(decode_att(attachments[1]["data"]), image_data) + # Make sure the image attachments are not treated as embedded: + self.assertNotIn('inline_images', params) + + def test_multiple_html_alternatives(self): + # Multiple alternatives not allowed + self.message.attach_alternative("

First html is OK

", "text/html") + self.message.attach_alternative("

But not second html

", "text/html") + with self.assertRaises(AnymailUnsupportedFeature): + self.message.send() + + def test_html_alternative(self): + # Only html alternatives allowed + self.message.attach_alternative("{'not': 'allowed'}", "application/json") + with self.assertRaises(AnymailUnsupportedFeature): + self.message.send() + + def test_alternatives_fail_silently(self): + # Make sure fail_silently is respected + self.message.attach_alternative("{'not': 'allowed'}", "application/json") + sent = self.message.send(fail_silently=True) + self.assert_esp_not_called("API should not be called when send fails silently") + self.assertEqual(sent, 0) + + def test_suppress_empty_address_lists(self): + """Empty to, cc, bcc, and reply_to shouldn't generate empty headers""" + self.message.send() + params = self.get_send_params() + self.assertNotIn('cc', params) + self.assertNotIn('bcc', params) + self.assertNotIn('reply_to', params) + + # Test empty `to` -- but send requires at least one recipient somewhere (like cc) + self.message.to = [] + self.message.cc = ['cc@example.com'] + self.message.send() + params = self.get_send_params() + self.assertNotIn('recipients', params) + + def test_api_failure(self): + failure_response = b"""{ "errors": [ { + "message": "Something went wrong", + "description": "Helpful explanation from your ESP" + } ] }""" + self.set_mock_failure(raw=failure_response) + with self.assertRaisesMessage(AnymailAPIError, "Helpful explanation from your ESP"): + self.message.send() + + def test_api_failure_fail_silently(self): + # Make sure fail_silently is respected + self.set_mock_failure() + sent = self.message.send(fail_silently=True) + self.assertEqual(sent, 0) + + +class SparkPostBackendAnymailFeatureTests(SparkPostBackendMockAPITestCase): + """Test backend support for Anymail added features""" + + def test_metadata(self): + self.message.metadata = {'user_id': "12345", 'items': 'spark, post'} + self.message.send() + params = self.get_send_params() + self.assertEqual(params['metadata'], {'user_id': "12345", 'items': 'spark, post'}) + + def test_send_at(self): + utc_plus_6 = get_fixed_timezone(6 * 60) + utc_minus_8 = get_fixed_timezone(-8 * 60) + + # SparkPost expects ISO-8601 YYYY-MM-DDTHH:MM:SS+-HH:MM + with override_current_timezone(utc_plus_6): + # Timezone-aware datetime converted to UTC: + self.message.send_at = datetime(2016, 3, 4, 5, 6, 7, tzinfo=utc_minus_8) + self.message.send() + params = self.get_send_params() + self.assertEqual(params['start_time'], "2016-03-04T05:06:07-08:00") + + # Explicit UTC: + self.message.send_at = datetime(2016, 3, 4, 5, 6, 7, tzinfo=utc) + self.message.send() + params = self.get_send_params() + self.assertEqual(params['start_time'], "2016-03-04T05:06:07+00:00") + + # Timezone-naive datetime assumed to be Django current_timezone + # (also checks stripping microseconds) + self.message.send_at = datetime(2022, 10, 11, 12, 13, 14, 567) + self.message.send() + params = self.get_send_params() + self.assertEqual(params['start_time'], "2022-10-11T12:13:14+06:00") + + # Date-only treated as midnight in current timezone + self.message.send_at = date(2022, 10, 22) + self.message.send() + params = self.get_send_params() + self.assertEqual(params['start_time'], "2022-10-22T00:00:00+06:00") + + # POSIX timestamp + self.message.send_at = 1651820889 # 2022-05-06 07:08:09 UTC + self.message.send() + params = self.get_send_params() + self.assertEqual(params['start_time'], "2022-05-06T07:08:09+00:00") + + # String passed unchanged (this is *not* portable between ESPs) + self.message.send_at = "2022-10-13T18:02:00-11:30" + self.message.send() + params = self.get_send_params() + self.assertEqual(params['start_time'], "2022-10-13T18:02:00-11:30") + + def test_tags(self): + self.message.tags = ["receipt"] + self.message.send() + params = self.get_send_params() + self.assertEqual(params['campaign'], "receipt") + + self.message.tags = ["receipt", "repeat-user"] + with self.assertRaisesMessage(AnymailUnsupportedFeature, 'multiple tags'): + self.message.send() + + def test_tracking(self): + # Test one way... + self.message.track_opens = True + self.message.track_clicks = False + self.message.send() + params = self.get_send_params() + self.assertEqual(params['track_opens'], True) + self.assertEqual(params['track_clicks'], False) + + # ...and the opposite way + self.message.track_opens = False + self.message.track_clicks = True + self.message.send() + params = self.get_send_params() + self.assertEqual(params['track_opens'], False) + self.assertEqual(params['track_clicks'], True) + + def test_template_id(self): + self.message.template_id = "welcome_template" + self.message.send() + params = self.get_send_params() + self.assertEqual(params['template'], "welcome_template") + + def test_merge_data(self): + self.set_mock_response(accepted=2) + self.message.to = ['alice@example.com', 'Bob '] + self.message.body = "Hi %recipient.name%. Welcome to %recipient.group% at %recipient.site%." + self.message.merge_data = { + 'alice@example.com': {'name': "Alice", 'group': "Developers"}, + 'bob@example.com': {'name': "Bob"}, # and leave group undefined + 'nobody@example.com': {'name': "Not a recipient for this message"}, + } + self.message.merge_global_data = {'group': "Users", 'site': "ExampleCo"} + self.message.send() + params = self.get_send_params() + self.assertEqual(params['recipients'], [ + {'address': {'email': 'alice@example.com'}, + 'substitution_data': {'name': "Alice", 'group': "Developers"}}, + {'address': {'email': 'bob@example.com', 'name': 'Bob'}, + 'substitution_data': {'name': "Bob"}} + ]) + self.assertEqual(params['substitution_data'], {'group': "Users", 'site': "ExampleCo"}) + + def test_default_omits_options(self): + """Make sure by default we don't send any ESP-specific options. + + Options not specified by the caller should be omitted entirely from + the API call (*not* sent as False or empty). This ensures + that your ESP account settings apply by default. + """ + self.message.send() + params = self.get_send_params() + self.assertNotIn('campaign', params) + self.assertNotIn('metadata', params) + self.assertNotIn('start_time', params) + self.assertNotIn('substitution_data', params) + self.assertNotIn('template', params) + self.assertNotIn('track_clicks', params) + self.assertNotIn('track_opens', params) + + def test_esp_extra(self): + self.message.esp_extra = { + 'future_sparkpost_send_param': 'some-value', + } + self.message.send() + params = self.get_send_params() + self.assertEqual(params['future_sparkpost_send_param'], 'some-value') + + def test_send_attaches_anymail_status(self): + """The anymail_status should be attached to the message when it is sent """ + response_content = { + 'id': '9876543210', + 'total_accepted_recipients': 1, + 'total_rejected_recipients': 0, + } + self.set_mock_response(raw=response_content) + msg = mail.EmailMessage('Subject', 'Message', 'from@example.com', ['to1@example.com'],) + sent = msg.send() + self.assertEqual(sent, 1) + self.assertEqual(msg.anymail_status.status, {'queued'}) + self.assertEqual(msg.anymail_status.message_id, '9876543210') + self.assertEqual(msg.anymail_status.recipients['to1@example.com'].status, 'queued') + self.assertEqual(msg.anymail_status.recipients['to1@example.com'].message_id, '9876543210') + self.assertEqual(msg.anymail_status.esp_response, response_content) + + @override_settings(ANYMAIL_IGNORE_RECIPIENT_STATUS=True) # exception is tested later + def test_send_all_rejected(self): + """The anymail_status should be 'rejected' when all recipients rejected""" + self.set_mock_response(accepted=0, rejected=2) + msg = mail.EmailMessage('Subject', 'Message', 'from@example.com', + ['to1@example.com', 'to2@example.com'],) + msg.send() + self.assertEqual(msg.anymail_status.status, {'rejected'}) + self.assertEqual(msg.anymail_status.recipients['to1@example.com'].status, 'rejected') + self.assertEqual(msg.anymail_status.recipients['to2@example.com'].status, 'rejected') + + def test_send_some_rejected(self): + """The anymail_status should be 'unknown' when some recipients accepted and some rejected""" + self.set_mock_response(accepted=1, rejected=1) + msg = mail.EmailMessage('Subject', 'Message', 'from@example.com', + ['to1@example.com', 'to2@example.com'],) + msg.send() + self.assertEqual(msg.anymail_status.status, {'unknown'}) + self.assertEqual(msg.anymail_status.recipients['to1@example.com'].status, 'unknown') + self.assertEqual(msg.anymail_status.recipients['to2@example.com'].status, 'unknown') + + def test_send_unexpected_count(self): + """The anymail_status should be 'unknown' when the total result count + doesn't match the number of recipients""" + self.set_mock_response(accepted=3, rejected=0) # but only 2 in the to-list + msg = mail.EmailMessage('Subject', 'Message', 'from@example.com', + ['to1@example.com', 'to2@example.com'],) + msg.send() + self.assertEqual(msg.anymail_status.status, {'unknown'}) + self.assertEqual(msg.anymail_status.recipients['to1@example.com'].status, 'unknown') + self.assertEqual(msg.anymail_status.recipients['to2@example.com'].status, 'unknown') + + # noinspection PyUnresolvedReferences + def test_send_failed_anymail_status(self): + """ If the send fails, anymail_status should contain initial values""" + self.set_mock_failure() + sent = self.message.send(fail_silently=True) + self.assertEqual(sent, 0) + self.assertIsNone(self.message.anymail_status.status) + self.assertIsNone(self.message.anymail_status.message_id) + self.assertEqual(self.message.anymail_status.recipients, {}) + self.assertIsNone(self.message.anymail_status.esp_response) + + # noinspection PyUnresolvedReferences + def test_send_unparsable_response(self): + """If the send succeeds, but result is unexpected format, should raise an API exception""" + response_content = {'wrong': 'format'} + self.set_mock_response(raw=response_content) + with self.assertRaises(AnymailAPIError): + self.message.send() + self.assertIsNone(self.message.anymail_status.status) + self.assertIsNone(self.message.anymail_status.message_id) + self.assertEqual(self.message.anymail_status.recipients, {}) + self.assertEqual(self.message.anymail_status.esp_response, response_content) + + # test_json_serialization_errors: + # Although SparkPost will raise JSON serialization errors, they're coming + # from deep within the python-sparkpost implementation. Since it's an + # implementation detail of that package, Anymail doesn't try to catch or + # modify those errors. + + +class SparkPostBackendRecipientsRefusedTests(SparkPostBackendMockAPITestCase): + """Should raise AnymailRecipientsRefused when *all* recipients are rejected or invalid""" + + def test_recipients_refused(self): + self.set_mock_response(accepted=0, rejected=2) + msg = mail.EmailMessage('Subject', 'Body', 'from@example.com', + ['invalid@localhost', 'reject@example.com']) + with self.assertRaises(AnymailRecipientsRefused): + msg.send() + + def test_fail_silently(self): + self.set_mock_response(accepted=0, rejected=2) + sent = mail.send_mail('Subject', 'Body', 'from@example.com', + ['invalid@localhost', 'reject@example.com'], + fail_silently=True) + self.assertEqual(sent, 0) + + def test_mixed_response(self): + """If *any* recipients are valid or queued, no exception is raised""" + self.set_mock_response(accepted=2, rejected=2) + msg = mail.EmailMessage('Subject', 'Body', 'from@example.com', + ['invalid@localhost', 'valid@example.com', + 'reject@example.com', 'also.valid@example.com']) + sent = msg.send() + self.assertEqual(sent, 1) # one message sent, successfully, to 2 of 4 recipients + status = msg.anymail_status + # We don't know which recipients were rejected + self.assertEqual(status.recipients['invalid@localhost'].status, 'unknown') + self.assertEqual(status.recipients['valid@example.com'].status, 'unknown') + self.assertEqual(status.recipients['reject@example.com'].status, 'unknown') + self.assertEqual(status.recipients['also.valid@example.com'].status, 'unknown') + + @override_settings(ANYMAIL_IGNORE_RECIPIENT_STATUS=True) + def test_settings_override(self): + """No exception with ignore setting""" + self.set_mock_response(accepted=0, rejected=2) + sent = mail.send_mail('Subject', 'Body', 'from@example.com', + ['invalid@localhost', 'reject@example.com']) + self.assertEqual(sent, 1) # refused message is included in sent count + + +@override_settings(EMAIL_BACKEND="anymail.backends.sparkpost.SparkPostBackend") +class SparkPostBackendImproperlyConfiguredTests(SimpleTestCase, AnymailTestMixin): + """Test ESP backend without required settings in place""" + + def test_missing_api_key(self): + with self.assertRaises(AnymailConfigurationError) as cm: + mail.get_connection() # this init's SparkPost without actually trying to send anything + errmsg = str(cm.exception) + # Make sure the error mentions the different places to set the key + self.assertRegex(errmsg, r'\bSPARKPOST_API_KEY\b') + self.assertRegex(errmsg, r'\bANYMAIL_SPARKPOST_API_KEY\b') + + def test_api_key_in_env(self): + """SparkPost package allows API key in env var; make sure Anymail works with that""" + with EnvironmentVarGuard() as env: + env['SPARKPOST_API_KEY'] = 'key_from_environment' + conn = mail.get_connection() + # Poke into implementation details to verify: + self.assertIsNone(conn.api_key) # Anymail prop + self.assertEqual(conn.sp.api_key, 'key_from_environment') # SparkPost prop diff --git a/tests/test_sparkpost_integration.py b/tests/test_sparkpost_integration.py new file mode 100644 index 0000000..9bf1ff3 --- /dev/null +++ b/tests/test_sparkpost_integration.py @@ -0,0 +1,116 @@ +from __future__ import unicode_literals + +import os +import unittest +from datetime import datetime, timedelta + +from django.test import SimpleTestCase +from django.test.utils import override_settings + +from anymail.exceptions import AnymailAPIError +from anymail.message import AnymailMessage + +from .utils import AnymailTestMixin, sample_image_path + +SPARKPOST_TEST_API_KEY = os.getenv('SPARKPOST_TEST_API_KEY') + + +@unittest.skipUnless(SPARKPOST_TEST_API_KEY, + "Set SPARKPOST_TEST_API_KEY environment variable " + "to run SparkPost integration tests") +@override_settings(ANYMAIL_SPARKPOST_API_KEY=SPARKPOST_TEST_API_KEY, + EMAIL_BACKEND="anymail.backends.sparkpost.SparkPostBackend") +class SparkPostBackendIntegrationTests(SimpleTestCase, AnymailTestMixin): + """SparkPost API integration tests + + These tests run against the **live** SparkPost API, using the + environment variable `SPARKPOST_TEST_API_KEY` as the API key + If that variable is not set, these tests won't run. + + SparkPost doesn't offer a test mode -- it tries to send everything + you ask. To avoid stacking up a pile of undeliverable @example.com + emails, the tests use SparkPost's "sink domain" @*.sink.sparkpostmail.com. + https://support.sparkpost.com/customer/en/portal/articles/2361300-how-to-test-integrations + + SparkPost also doesn't support arbitrary senders (so no from@example.com). + We've set up @test-sp.anymail.info as a validated sending domain for these tests. + + """ + + def setUp(self): + super(SparkPostBackendIntegrationTests, self).setUp() + self.message = AnymailMessage('Anymail SparkPost integration test', 'Text content', + 'test@test-sp.anymail.info', ['to@test.sink.sparkpostmail.com']) + self.message.attach_alternative('

HTML content

', "text/html") + + def test_simple_send(self): + # Example of getting the SparkPost send status and transmission id from the message + sent_count = self.message.send() + self.assertEqual(sent_count, 1) + + anymail_status = self.message.anymail_status + sent_status = anymail_status.recipients['to@test.sink.sparkpostmail.com'].status + message_id = anymail_status.recipients['to@test.sink.sparkpostmail.com'].message_id + + self.assertEqual(sent_status, 'queued') # SparkPost always queues + self.assertRegex(message_id, r'.+') # this is actually the transmission_id; should be non-blank + self.assertEqual(anymail_status.status, {sent_status}) # set of all recipient statuses + self.assertEqual(anymail_status.message_id, message_id) + + def test_all_options(self): + send_at = datetime.now() + timedelta(minutes=2) + message = AnymailMessage( + subject="Anymail all-options integration test", + body="This is the text body", + from_email="Test From ", + to=["to1@test.sink.sparkpostmail.com", "Recipient 2 "], + cc=["cc1@test.sink.sparkpostmail.com", "Copy 2 "], + bcc=["bcc1@test.sink.sparkpostmail.com", "Blind Copy 2 "], + reply_to=["reply1@example.com", "Reply 2 "], + headers={"X-Anymail-Test": "value"}, + + metadata={"meta1": "simple string", "meta2": 2}, + send_at=send_at, + tags=["tag 1"], # SparkPost only supports single tags + track_clicks=True, + track_opens=True, + ) + message.attach("attachment1.txt", "Here is some\ntext for you", "text/plain") + message.attach("attachment2.csv", "ID,Name\n1,Amy Lina", "text/csv") + cid = message.attach_inline_image_file(sample_image_path()) + message.attach_alternative( + "

HTML: with link" + "and image: " % cid, + "text/html") + + message.send() + self.assertEqual(message.anymail_status.status, {'queued'}) # SparkPost always queues + + def test_merge_data(self): + message = AnymailMessage( + subject="Anymail merge_data test: {{ value }}", + body="This body includes merge data: {{ value }}\n" + "And global merge data: {{ global }}", + from_email="Test From ", + to=["to1@test.sink.sparkpostmail.com", "Recipient 2 "], + merge_data={ + 'to1@test.sink.sparkpostmail.com': {'value': 'one'}, + 'to2@test.sink.sparkpostmail.com': {'value': 'two'}, + }, + merge_global_data={ + 'global': 'global_value' + }, + ) + message.send() + recipient_status = message.anymail_status.recipients + self.assertEqual(recipient_status['to1@test.sink.sparkpostmail.com'].status, 'queued') + self.assertEqual(recipient_status['to2@test.sink.sparkpostmail.com'].status, 'queued') + + @override_settings(ANYMAIL_SPARKPOST_API_KEY="Hey, that's not an API key!") + def test_invalid_api_key(self): + with self.assertRaises(AnymailAPIError) as cm: + self.message.send() + err = cm.exception + self.assertEqual(err.status_code, 403) + # Make sure the exception message includes SparkPost's response: + self.assertIn("Forbidden", str(err)) diff --git a/tests/test_sparkpost_webhooks.py b/tests/test_sparkpost_webhooks.py new file mode 100644 index 0000000..a7f21ee --- /dev/null +++ b/tests/test_sparkpost_webhooks.py @@ -0,0 +1,263 @@ +import json +from datetime import datetime + +from django.utils.timezone import utc +from mock import ANY + +from anymail.signals import AnymailTrackingEvent +from anymail.webhooks.sparkpost import SparkPostTrackingWebhookView + +from .webhook_cases import WebhookBasicAuthTestsMixin, WebhookTestCase + + +class SparkPostWebhookSecurityTestCase(WebhookTestCase, WebhookBasicAuthTestsMixin): + def call_webhook(self): + return self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps([])) + + # Actual tests are in WebhookBasicAuthTestsMixin + + +class SparkPostDeliveryTestCase(WebhookTestCase): + + def test_ping_event(self): + raw_events = [{'msys': {}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + self.assertFalse(self.tracking_handler.called) # no real events + + def test_injection_event(self): + # Full event from SparkPost sample events API. (Later tests omit unused event fields.) + raw_events = [{"msys": {"message_event": { + "type": "injection", + "campaign_id": "Example Campaign Name", + "customer_id": "1", + "event_id": "92356927693813856", + "friendly_from": "sender@example.com", + "ip_pool": "Example-Ip-Pool", + "message_id": "000443ee14578172be22", + "msg_from": "sender@example.com", + "msg_size": "1337", + "rcpt_meta": {"customKey": "customValue"}, + "rcpt_tags": ["male", "US"], + "rcpt_to": "recipient@example.com", + "raw_rcpt_to": "recipient@example.com", + "rcpt_type": "cc", + "routing_domain": "example.com", + "sending_ip": "127.0.0.1", + "sms_coding": "ASCII", + "sms_dst": "7876712656", + "sms_dst_npi": "E164", + "sms_dst_ton": "International", + "sms_segments": 5, + "sms_src": "1234", + "sms_src_npi": "E164", + "sms_src_ton": "Unknown", + "sms_text": "lol", + "subaccount_id": "101", + "subject": "Summer deals are here!", + "template_id": "templ-1234", + "template_version": "1", + "timestamp": "1454442600", + "transmission_id": "65832150921904138" + }}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "queued") + self.assertEqual(event.timestamp, datetime(2016, 2, 2, 19, 50, 00, tzinfo=utc)) + self.assertEqual(event.esp_event, raw_events[0]) + self.assertEqual(event.message_id, "65832150921904138") # actually transmission_id + self.assertEqual(event.event_id, "92356927693813856") + self.assertEqual(event.recipient, "recipient@example.com") + self.assertEqual(event.tags, ["Example Campaign Name"]) # campaign_id (rcpt_tags not available at send) + self.assertEqual(event.metadata, {"customKey": "customValue"}) # includes transmissions.send metadata + + def test_delivery_event(self): + raw_events = [{"msys": {"message_event": { + "type": "delivery", + "event_id": "92356927693813856", + "rcpt_to": "recipient@example.com", + "raw_rcpt_to": "Recipient@example.com", + "rcpt_meta": {}, + "timestamp": "1454442600", + "transmission_id": "65832150921904138" + }}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "delivered") + self.assertEqual(event.recipient, "Recipient@example.com") + self.assertEqual(event.tags, None) + self.assertEqual(event.metadata, None) + + def test_bounce_event(self): + raw_events = [{ + "msys": {"message_event": { + "type": "bounce", + "bounce_class": "10", + "customer_id": "00000", + "error_code": "550", + "event_id": "84345317653491230", + "message_id": "0004e3724f57753a3561", + "raw_rcpt_to": "bounce@example.com", + "raw_reason": "550 5.1.1 : Recipient address rejected: User unknown", + "rcpt_to": "bounce@example.com", + "reason": "550 5.1.1 ...@... Recipient address rejected: ...", + "timestamp": "1464824548", + "transmission_id": "84345317650824116", + }}, + "cust": {"id": "00000"} # Included in real (non-example) event data + }] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "bounced") + self.assertEqual(event.esp_event, raw_events[0]) + self.assertEqual(event.message_id, "84345317650824116") # transmission_id + self.assertEqual(event.event_id, "84345317653491230") + self.assertEqual(event.recipient, "bounce@example.com") + self.assertEqual(event.reject_reason, "invalid") + self.assertEqual(event.mta_response, + "550 5.1.1 : Recipient address rejected: User unknown") + + def test_delay_event(self): + raw_events = [{"msys": {"message_event": { + "type": "delay", + "bounce_class": "21", + "error_code": "454", + "event_id": "84345317653675522", + "message_id": "0004e3724f57753a3861", + "num_retries": "1", + "queue_time": "1200161", + "raw_rcpt_to": "recipient@nomx.example.com", + "raw_reason": "454 4.4.4 [internal] no MX or A for domain", + "rcpt_to": "recipient@nomx.example.com", + "reason": "454 4.4.4 [internal] no MX or A for domain", + "timestamp": "1464825748", + "transmission_id": "84345317650824116", + }}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "deferred") + self.assertEqual(event.esp_event, raw_events[0]) + self.assertEqual(event.recipient, "recipient@nomx.example.com") + self.assertEqual(event.mta_response, "454 4.4.4 [internal] no MX or A for domain") + + def test_unsubscribe_event(self): + raw_events = [{"msys": {"unsubscribe_event": { + "type": "list_unsubscribe", + "event_id": "66331590532986193", + "message_id": "0004278150574660124d", + "raw_rcpt_to": "recipient@example.com", + "rcpt_to": "recipient@example.com", + "timestamp": "1464894280", + "transmission_id": "84345993965073285", + }}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "unsubscribed") + self.assertEqual(event.recipient, "recipient@example.com") + + def test_generation_rejection_event(self): + # This is what you get if you try to send to a suppressed address + raw_events = [{"msys": {"gen_event": { + "type": "generation_rejection", + "error_code": "554", + "event_id": "102360394390563734", + "message_id": "0005c29950577c61695d", + "raw_rcpt_to": "suppressed@example.com", + "raw_reason": "554 5.7.1 recipient address suppressed due to customer policy", + "rcpt_to": "suppressed@example.com", + "reason": "554 5.7.1 recipient address suppressed due to customer policy", + "timestamp": "1464900034", + "transmission_id": "102360394387646691", + }}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "rejected") + self.assertEqual(event.recipient, "suppressed@example.com") + self.assertEqual(event.mta_response, "554 5.7.1 recipient address suppressed due to customer policy") + + def test_bounce_challenge_response(self): + # Test for changing initial event_type based on bounce_class + raw_events = [{"msys": {"message_event": { + "type": "bounce", + "bounce_class": "60", + "raw_rcpt_to": "vacationing@example.com", + "rcpt_to": "vacationing@example.com", + }}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "autoresponded") + self.assertEqual(event.reject_reason, "other") + self.assertEqual(event.recipient, "vacationing@example.com") + + def test_open_event(self): + raw_events = [{"msys": {"track_event": { + "type": "open", + "raw_rcpt_to": "recipient@example.com", + "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36", + }}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "opened") + self.assertEqual(event.user_agent, "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36") + + def test_click_event(self): + raw_events = [{"msys": {"track_event": { + "type": "click", + "raw_rcpt_to": "recipient@example.com", + "target_link_name": "Example Link Name", + "target_link_url": "http://example.com", + "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36", + }}}] + response = self.client.post('/anymail/sparkpost/tracking/', + content_type='application/json', data=json.dumps(raw_events)) + self.assertEqual(response.status_code, 200) + kwargs = self.assert_handler_called_once_with(self.tracking_handler, sender=SparkPostTrackingWebhookView, + event=ANY, esp_name='SparkPost') + event = kwargs['event'] + self.assertIsInstance(event, AnymailTrackingEvent) + self.assertEqual(event.event_type, "clicked") + self.assertEqual(event.recipient, "recipient@example.com") + self.assertEqual(event.user_agent, "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_3) AppleWebKit/537.36") + self.assertEqual(event.click_url, "http://example.com")