Event-tracking webhooks

Closes #3

Author: medmunds

anymail/compat.py

@@ -1,6 +1,6 @@
 import json
 
-from django.core.exceptions import ImproperlyConfigured
+from django.core.exceptions import ImproperlyConfigured, SuspiciousOperation
 from requests import HTTPError
 
 
@@ -125,6 +125,14 @@ def __init__(self, message=None, orig_err=None, *args, **kwargs):
         super(AnymailSerializationError, self).__init__(message, *args, **kwargs)
 
 
+class AnymailWebhookValidationFailure(AnymailError, SuspiciousOperation):
+    """Exception when a webhook cannot be validated.
+
+    Django's SuspiciousOperation turns into
+    an HTTP 400 error in production.
+    """
+
+
 class AnymailConfigurationError(ImproperlyConfigured):
     """Exception for Anymail configuration or installation issues"""
     # This deliberately doesn't inherit from AnymailError,
@@ -140,3 +148,12 @@ def __init__(self, missing_package, backend="<backend>"):
                   "with your desired backends)" % (missing_package, backend)
         super(AnymailImproperlyInstalled, self).__init__(message)
 
+
+# Warnings
+
+class AnymailWarning(Warning):
+    """Base warning for Anymail"""
+
+
+class AnymailInsecureWebhookWarning(AnymailWarning):
+    """Warns when webhook configured without any validation"""

anymail/exceptions.py

@@ -1,3 +1,82 @@
 from django.dispatch import Signal
 
-webhook_event = Signal(providing_args=['event_type', 'data'])
+
+# Delivery and tracking events for sent messages
+tracking = Signal(providing_args=['event', 'esp_name'])
+
+# Event for receiving inbound messages
+inbound = Signal(providing_args=['event', 'esp_name'])
+
+
+class AnymailEvent(object):
+    """Base class for normalized Anymail webhook events"""
+
+    def __init__(self, event_type, timestamp=None, event_id=None, esp_event=None, **kwargs):
+        self.event_type = event_type  # normalized to an EventType str
+        self.timestamp = timestamp  # normalized to an aware datetime
+        self.event_id = event_id  # opaque str
+        self.esp_event = esp_event  # raw event fields (e.g., parsed JSON dict or POST data QueryDict)
+
+
+class AnymailTrackingEvent(AnymailEvent):
+    """Normalized delivery and tracking event for sent messages"""
+
+    def __init__(self, **kwargs):
+        super(AnymailTrackingEvent, self).__init__(**kwargs)
+        self.click_url = kwargs.pop('click_url', None)  # str
+        self.description = kwargs.pop('description', None)  # str, usually human-readable, not normalized
+        self.message_id = kwargs.pop('message_id', None)  # str, format may vary
+        self.metadata = kwargs.pop('metadata', None)  # dict
+        self.mta_response = kwargs.pop('mta_response', None)  # str, may include SMTP codes, not normalized
+        self.recipient = kwargs.pop('recipient', None)  # str email address (just the email portion; no name)
+        self.reject_reason = kwargs.pop('reject_reason', None)  # normalized to a RejectReason str
+        self.tags = kwargs.pop('tags', None)  # list of str
+        self.user_agent = kwargs.pop('user_agent', None)  # str
+
+
+class AnymailInboundEvent(AnymailEvent):
+    """Normalized inbound message event"""
+
+    def __init__(self, **kwargs):
+        super(AnymailInboundEvent, self).__init__(**kwargs)
+
+
+class EventType:
+    """Constants for normalized Anymail event types"""
+
+    # Delivery (and non-delivery) event types:
+    # (these match message.ANYMAIL_STATUSES where appropriate)
+    QUEUED = 'queued'  # the ESP has accepted the message and will try to send it (possibly later)
+    SENT = 'sent'  # the ESP has sent the message (though it may or may not get delivered)
+    REJECTED = 'rejected'  # the ESP refused to send the messsage (e.g., suppression list, policy, invalid email)
+    FAILED = 'failed'  # the ESP was unable to send the message (e.g., template rendering error)
+
+    BOUNCED = 'bounced'  # rejected or blocked by receiving MTA
+    DEFERRED = 'deferred'  # delayed by receiving MTA; should be followed by a later BOUNCED or DELIVERED
+    DELIVERED = 'delivered'  # accepted by receiving MTA
+    AUTORESPONDED = 'autoresponded'  # a bot replied
+
+    # Tracking event types:
+    OPENED = 'opened'  # open tracking
+    CLICKED = 'clicked'  # click tracking
+    COMPLAINED = 'complained'  # recipient reported as spam (e.g., through feedback loop)
+    UNSUBSCRIBED = 'unsubscribed'  # recipient attempted to unsubscribe
+    SUBSCRIBED = 'subscribed'  # signed up for mailing list through ESP-hosted form
+
+    # Inbound event types:
+    INBOUND = 'inbound'  # received message
+    INBOUND_FAILED = 'inbound_failed'
+
+    # Other:
+    UNKNOWN = 'unknown'  # anything else
+
+
+class RejectReason:
+    """Constants for normalized Anymail reject/drop reasons"""
+    INVALID = 'invalid'  # bad address format
+    BOUNCED = 'bounced'  # (previous) bounce from recipient
+    TIMED_OUT = 'timed_out'  # (previous) repeated failed delivery attempts
+    BLOCKED = 'blocked'  # ESP policy suppression
+    SPAM = 'spam'  # (previous) spam complaint from recipient
+    UNSUBSCRIBED = 'unsubscribed'  # (previous) unsubscribe request from recipient
+    OTHER = 'other'

anymail/signals.py

@@ -1,11 +1,15 @@
-try:
-    from django.conf.urls import url
-except ImportError:
-    from django.conf.urls.defaults import url
+from django.conf.urls import url
 
-from .views import DjrillWebhookView
+from .webhooks.mailgun import MailgunTrackingWebhookView
+from .webhooks.mandrill import MandrillTrackingWebhookView
+from .webhooks.postmark import PostmarkTrackingWebhookView
+from .webhooks.sendgrid import SendGridTrackingWebhookView
 
 
+app_name = 'anymail'
 urlpatterns = [
-    url(r'^webhook/$', DjrillWebhookView.as_view(), name='djrill_webhook'),
+    url(r'^mailgun/tracking/$', MailgunTrackingWebhookView.as_view(), name='mailgun_tracking_webhook'),
+    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'),
 ]

anymail/urls.py

@@ -70,6 +70,29 @@ def last(*args):
     return UNSET
 
 
+def getfirst(dct, keys, default=UNSET):
+    """Returns the value of the first of keys found in dict dct.
+
+    >>> getfirst({'a': 1, 'b': 2}, ['c', 'a'])
+    1
+    >>> getfirst({'a': 1, 'b': 2}, ['b', 'a'])
+    2
+    >>> getfirst({'a': 1, 'b': 2}, ['c'])
+    KeyError
+    >>> getfirst({'a': 1, 'b': 2}, ['c'], None)
+    None
+    """
+    for key in keys:
+        try:
+            return dct[key]
+        except KeyError:
+            pass
+    if default is UNSET:
+        raise KeyError("None of %s found in dict" % ', '.join(keys))
+    else:
+        return default
+
+
 class ParsedEmail(object):
     """A sanitized, full email address with separate name and email properties"""
 
@@ -215,6 +238,27 @@ def get_anymail_setting(name, default=UNSET, esp_name=None, kwargs=None, allow_b
                 return default
 
 
+def collect_all_methods(cls, method_name):
+    """Return list of all `method_name` methods for cls and its superclass chain.
+
+    List is in MRO order, with no duplicates. Methods are unbound.
+
+    (This is used to simplify mixins and subclasses that contribute to a method set,
+    without requiring superclass chaining, and without requiring cooperating
+    superclasses.)
+    """
+    methods = []
+    for ancestor in cls.__mro__:
+        try:
+            validator = getattr(ancestor, method_name)
+        except AttributeError:
+            pass
+        else:
+            if validator not in methods:
+                methods.append(validator)
+    return methods
+
+
 EPOCH = datetime(1970, 1, 1, tzinfo=utc)