From e15cb46dafcf0d1650b9e2e872740dcb59981a3f Mon Sep 17 00:00:00 2001 From: medmunds Date: Fri, 11 Mar 2016 16:17:02 -0800 Subject: [PATCH] Implement SendGridBackend Covers most of #1 --- anymail/backends/sendgrid.py | 195 ++++++++ anymail/exceptions.py | 6 +- anymail/tests/test_sendgrid_backend.py | 540 +++++++++++++++++++++ anymail/tests/test_sendgrid_integration.py | 96 ++++ docs/esps/sendgrid.rst | 127 ++++- setup.py | 1 + 6 files changed, 954 insertions(+), 11 deletions(-) create mode 100644 anymail/backends/sendgrid.py create mode 100644 anymail/tests/test_sendgrid_backend.py create mode 100644 anymail/tests/test_sendgrid_integration.py diff --git a/anymail/backends/sendgrid.py b/anymail/backends/sendgrid.py new file mode 100644 index 0000000..a452dbc --- /dev/null +++ b/anymail/backends/sendgrid.py @@ -0,0 +1,195 @@ +from django.core.mail import make_msgid + +from ..exceptions import AnymailImproperlyInstalled, AnymailRequestsAPIError +from ..message import AnymailRecipientStatus +from ..utils import get_anymail_setting, timestamp + +from .base_requests import AnymailRequestsBackend, RequestsPayload + +try: + # noinspection PyUnresolvedReferences + from requests.structures import CaseInsensitiveDict +except ImportError: + raise AnymailImproperlyInstalled('requests', backend="sendgrid") + + +class SendGridBackend(AnymailRequestsBackend): + """ + SendGrid API Email Backend + """ + + def __init__(self, **kwargs): + """Init options from Django settings""" + self.api_key = get_anymail_setting('SENDGRID_API_KEY', allow_bare=True) + # This is SendGrid's Web API v2 (because the Web API v3 doesn't support sending) + api_url = get_anymail_setting("SENDGRID_API_URL", "https://api.sendgrid.com/api/") + if not api_url.endswith("/"): + api_url += "/" + super(SendGridBackend, self).__init__(api_url, **kwargs) + + def build_message_payload(self, message, defaults): + return SendGridPayload(message, defaults, self) + + def parse_recipient_status(self, response, payload, message): + parsed_response = self.deserialize_json_response(response, payload, message) + try: + sendgrid_message = parsed_response["message"] + except (KeyError, TypeError): + raise AnymailRequestsAPIError("Invalid SendGrid API response format", + email_message=message, payload=payload, response=response) + if sendgrid_message != "success": + errors = parsed_response.get("errors", []) + raise AnymailRequestsAPIError("SendGrid send failed: '%s'" % "; ".join(errors), + email_message=message, payload=payload, response=response) + # Simulate a per-recipient status of "queued": + status = AnymailRecipientStatus(message_id=payload.message_id, status="queued") + return {recipient.email: status for recipient in payload.all_recipients} + + +class SendGridPayload(RequestsPayload): + + def __init__(self, message, defaults, backend, *args, **kwargs): + self.all_recipients = [] # used for backend.parse_recipient_status + self.message_id = None # Message-ID -- assigned in serialize_data unless provided in headers + self.smtpapi = {} # SendGrid x-smtpapi field + + auth_headers = {'Authorization': 'Bearer ' + backend.api_key} + super(SendGridPayload, self).__init__(message, defaults, backend, + headers=auth_headers, *args, **kwargs) + + def get_api_endpoint(self): + return "mail.send.json" + + def serialize_data(self): + """Performs any necessary serialization on self.data, and returns the result.""" + + # Serialize x-smtpapi to json: + if len(self.smtpapi) > 0: + # If esp_extra was also used to set x-smtpapi, need to merge it + if "x-smtpapi" in self.data: + esp_extra_smtpapi = self.data["x-smtpapi"] + self.smtpapi.update(esp_extra_smtpapi) # need to make this deep merge (for filters)! + self.data["x-smtpapi"] = self.serialize_json(self.smtpapi) + elif "x-smtpapi" in self.data: + self.data["x-smtpapi"] = self.serialize_json(self.data["x-smtpapi"]) + + # Add our own message_id, and serialize extra headers to json: + headers = self.data["headers"] + try: + self.message_id = headers["Message-ID"] + except KeyError: + self.message_id = headers["Message-ID"] = self.make_message_id() + self.data["headers"] = self.serialize_json(dict(headers.items())) + + return self.data + + def make_message_id(self): + """Returns a Message-ID that could be used for this payload + + Tries to use the from_email's domain as the Message-ID's domain + """ + try: + _, domain = self.data["from"].split("@") + except (AttributeError, KeyError, TypeError, ValueError): + domain = None + return make_msgid(domain=domain) + + # + # Payload construction + # + + def init_payload(self): + self.data = {} # {field: [multiple, values]} + self.files = {} + self.data['headers'] = CaseInsensitiveDict() # headers keys are case-insensitive + + def set_from_email(self, email): + self.data["from"] = email.email + if email.name: + self.data["fromname"] = email.name + + def set_recipients(self, recipient_type, emails): + assert recipient_type in ["to", "cc", "bcc"] + if emails: + self.data[recipient_type] = [email.email for email in emails] + empty_name = " " # SendGrid API balks on complete empty name fields + self.data[recipient_type + "name"] = [email.name or empty_name for email in emails] + self.all_recipients += emails # used for backend.parse_recipient_status + + def set_subject(self, subject): + self.data["subject"] = subject + + def set_reply_to(self, emails): + # Note: SendGrid mangles the 'replyto' API param: it drops + # all but the last email in a multi-address replyto, and + # drops all the display names. [tested 2016-03-10] + # + # To avoid those quirks, we provide a fully-formed Reply-To + # in the custom headers, which makes it through intact. + if emails: + reply_to = ", ".join([email.address for email in emails]) + self.data["headers"]["Reply-To"] = reply_to + + def set_extra_headers(self, headers): + # SendGrid requires header values to be strings -- not integers. + # We'll stringify ints and floats; anything else is the caller's responsibility. + # (This field gets converted to json in self.serialize_data) + self.data["headers"].update({ + k: str(v) if isinstance(v, (int, float)) else v + for k, v in headers.items() + }) + + def set_text_body(self, body): + self.data["text"] = body + + def set_html_body(self, body): + if "html" in self.data: + # second html body could show up through multiple alternatives, or html body + alternative + self.unsupported_feature("multiple html parts") + self.data["html"] = body + + def add_attachment(self, attachment): + filename = attachment.name or "" + if attachment.inline: + filename = filename or attachment.cid # must have non-empty name for the cid matching + content_field = "content[%s]" % filename + self.data[content_field] = attachment.cid + + files_field = "files[%s]" % filename + if files_field in self.files: + # It's possible SendGrid could actually handle this case (needs testing), + # but requests doesn't seem to accept a list of tuples for a files field. + # (See the MailgunBackend version for a different approach that might work.) + self.unsupported_feature( + "multiple attachments with the same filename ('%s')" % filename if filename + else "multiple unnamed attachments") + + self.files[files_field] = (filename, attachment.content, attachment.mimetype) + + def set_metadata(self, metadata): + self.smtpapi['unique_args'] = metadata + + def set_send_at(self, send_at): + # Backend has converted pretty much everything to + # a datetime by here; SendGrid expects unix timestamp + self.smtpapi["send_at"] = int(timestamp(send_at)) # strip microseconds + + def set_tags(self, tags): + self.smtpapi["category"] = tags + + def add_filter(self, filter_name, setting, val): + self.smtpapi.setdefault('filters', {})\ + .setdefault(filter_name, {})\ + .setdefault('settings', {})[setting] = val + + def set_track_clicks(self, track_clicks): + self.add_filter('clicktrack', 'enable', int(track_clicks)) + + def set_track_opens(self, track_opens): + # SendGrid's opentrack filter also supports a "replace" + # parameter, which Anymail doesn't offer directly. + # (You could add it through esp_extra.) + self.add_filter('opentrack', 'enable', int(track_opens)) + + def set_esp_extra(self, extra): + self.data.update(extra) diff --git a/anymail/exceptions.py b/anymail/exceptions.py index d4eada5..89610e7 100644 --- a/anymail/exceptions.py +++ b/anymail/exceptions.py @@ -134,9 +134,9 @@ class AnymailSerializationError(AnymailError, TypeError): # This deliberately doesn't inherit from AnymailError class AnymailImproperlyInstalled(ImproperlyConfigured, ImportError): - def __init__(self, missing_package): + def __init__(self, missing_package, backend=""): message = "The %s package is required to use this backend, but isn't installed.\n" \ - "(Be sure to use `pip install django-anymail[]` " \ - "with your desired backends)" % missing_package + "(Be sure to use `pip install django-anymail[%s]` " \ + "with your desired backends)" % (missing_package, backend) super(AnymailImproperlyInstalled, self).__init__(message) diff --git a/anymail/tests/test_sendgrid_backend.py b/anymail/tests/test_sendgrid_backend.py new file mode 100644 index 0000000..0a7208c --- /dev/null +++ b/anymail/tests/test_sendgrid_backend.py @@ -0,0 +1,540 @@ +# -*- coding: utf-8 -*- + +from __future__ import unicode_literals + +import json +from calendar import timegm +from datetime import date, datetime +from decimal import Decimal +from email.mime.base import MIMEBase +from email.mime.image import MIMEImage + +from django.core import mail +from django.core.exceptions import ImproperlyConfigured +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 + +from anymail.exceptions import AnymailAPIError, AnymailSerializationError, AnymailUnsupportedFeature +from anymail.message import attach_inline_image + +from .mock_requests_backend import RequestsBackendMockAPITestCase +from .utils import sample_image_content, sample_image_path, SAMPLE_IMAGE_FILENAME, AnymailTestMixin + + +@override_settings(EMAIL_BACKEND='anymail.backends.sendgrid.SendGridBackend', + ANYMAIL={'SENDGRID_API_KEY': 'test_api_key'}) +class SendGridBackendMockAPITestCase(RequestsBackendMockAPITestCase): + DEFAULT_RAW_RESPONSE = b"""{ + "message": "success" + }""" + + def setUp(self): + super(SendGridBackendMockAPITestCase, self).setUp() + # Simple message useful for many tests + self.message = mail.EmailMultiAlternatives('Subject', 'Text Body', 'from@example.com', ['to@example.com']) + + def get_smtpapi(self): + """Returns the x-smtpapi data passed to the mock requests call""" + data = self.get_api_call_data() + return json.loads(data["x-smtpapi"]) + + +class SendGridBackendStandardEmailTests(SendGridBackendMockAPITestCase): + """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@sender.example.com', ['to@example.com'], fail_silently=False) + self.assert_esp_called('/api/mail.send.json') + headers = self.get_api_call_headers() + self.assertEqual(headers["Authorization"], "Bearer test_api_key") + data = self.get_api_call_data() + self.assertEqual(data['subject'], "Subject here") + self.assertEqual(data['text'], "Here is the message.") + self.assertEqual(data['from'], "from@sender.example.com") + self.assertEqual(data['to'], ["to@example.com"]) + # make sure backend assigned a Message-ID for event tracking + headers = json.loads(data['headers']) + self.assertRegex(headers['Message-ID'], r'\<.+@sender\.example\.com\>') # id uses from_email's domain + + def test_name_addr(self): + """Make sure RFC2822 name-addr format (with display-name) is allowed + + (Test both sender and recipient addresses) + """ + 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() + data = self.get_api_call_data() + self.assertEqual(data['from'], "from@example.com") + self.assertEqual(data['fromname'], "From Name") + self.assertEqual(data['to'], ['to1@example.com', 'to2@example.com']) + self.assertEqual(data['toname'], ['Recipient #1', ' ']) # note space -- SendGrid balks on '' + self.assertEqual(data['cc'], ['cc1@example.com', 'cc2@example.com']) + self.assertEqual(data['ccname'], ['Carbon Copy', ' ']) + self.assertEqual(data['bcc'], ['bcc1@example.com', 'bcc2@example.com']) + self.assertEqual(data['bccname'], ['Blind Copy', ' ']) + + def test_email_message(self): + 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@sales.example.com'}) # should override backend msgid + email.send() + data = self.get_api_call_data() + self.assertEqual(data['subject'], "Subject") + self.assertEqual(data['text'], "Body goes here") + self.assertEqual(data['from'], "from@example.com") + self.assertEqual(data['to'], ['to1@example.com', 'to2@example.com']) + self.assertEqual(data['toname'], [' ', 'Also To']) + self.assertEqual(data['bcc'], ['bcc1@example.com', 'bcc2@example.com']) + self.assertEqual(data['bccname'], [' ', 'Also BCC']) + self.assertEqual(data['cc'], ['cc1@example.com', 'cc2@example.com']) + self.assertEqual(data['ccname'], [' ', 'Also CC']) + self.assertJSONEqual(data['headers'], { + 'Message-ID': 'mycustommsgid@sales.example.com', + 'Reply-To': 'another@example.com', + 'X-MyHeader': 'my value', + }) + + 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() + data = self.get_api_call_data() + self.assertEqual(data['text'], text_content) + self.assertEqual(data['html'], html_content) + # Don't accidentally send the html part as an attachment: + files = self.get_api_call_files(required=False) + self.assertIsNone(files) + + 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() + data = self.get_api_call_data() + self.assertNotIn('text', data) + self.assertEqual(data['html'], html_content) + + def test_extra_headers(self): + self.message.extra_headers = {'X-Custom': 'string', 'X-Num': 123} + self.message.send() + data = self.get_api_call_data() + headers = json.loads(data['headers']) + self.assertEqual(headers['X-Custom'], 'string') + self.assertEqual(headers['X-Num'], '123') # number converted to string (per SendGrid requirement) + + def test_extra_headers_serialization_error(self): + self.message.extra_headers = {'X-Custom': Decimal(12.5)} + with self.assertRaisesMessage(AnymailSerializationError, "Decimal('12.5')"): + self.message.send() + + def test_reply_to(self): + # reply_to is new in Django 1.8 -- before that, you can simply include it in headers + try: + # noinspection PyArgumentList + email = mail.EmailMessage('Subject', 'Body goes here', 'from@example.com', ['to1@example.com'], + reply_to=['reply@example.com', 'Other '], + headers={'X-Other': 'Keep'}) + except TypeError: + # Pre-Django 1.8 + return self.skipTest("Django version doesn't support EmailMessage(reply_to)") + email.send() + data = self.get_api_call_data() + self.assertNotIn('replyto', data) # don't use SendGrid's replyto (it's broken); just use headers + headers = json.loads(data['headers']) + self.assertEqual(headers['Reply-To'], 'reply@example.com, Other ') + self.assertEqual(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 data" + mimeattachment = MIMEBase('application', 'pdf') + mimeattachment.set_payload(pdf_content) + self.message.attach(mimeattachment) + + self.message.send() + files = self.get_api_call_files() + self.assertEqual(files, { + 'files[test.txt]': ('test.txt', text_content, 'text/plain'), + 'files[test.png]': ('test.png', png_content, 'image/png'), # type inferred from filename + 'files[]': ('', pdf_content, 'application/pdf'), # no filename + }) + + def test_attachment_name_conflicts(self): + # It's not clear how to (or whether) supply multiple attachments with + # the same name to SendGrid's API. Anymail treats this case as unsupported. + self.message.attach('foo.txt', 'content', 'text/plain') + self.message.attach('bar.txt', 'content', 'text/plain') + self.message.attach('foo.txt', 'different content', 'text/plain') + with self.assertRaisesMessage(AnymailUnsupportedFeature, + "multiple attachments with the same filename") as cm: + self.message.send() + self.assertIn('foo.txt', str(cm.exception)) # say which filename + + def test_unnamed_attachment_conflicts(self): + # Same as previous test, but with None/empty filenames + self.message.attach(None, 'content', 'text/plain') + self.message.attach('', 'different content', 'text/plain') + with self.assertRaisesMessage(AnymailUnsupportedFeature, "multiple unnamed attachments"): + self.message.send() + + 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() + files = self.get_api_call_files() + self.assertEqual(files['files[Une pièce jointe.html]'], + ('Une pièce jointe.html', '

\u2019

', 'text/html')) + + def test_embedded_images(self): + image_data = sample_image_content() # Read from a png file + cid = attach_inline_image(self.message, image_data) + html_content = '

This has an inline image.

' % cid + self.message.attach_alternative(html_content, "text/html") + + self.message.send() + data = self.get_api_call_data() + self.assertEqual(data['html'], html_content) + + files = self.get_api_call_files() + filename = cid # (for now) + self.assertEqual(files, { + 'files[%s]' % filename: (filename, image_data, "image/png"), + }) + self.assertEqual(data['content[%s]' % filename], cid) + + 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() + files = self.get_api_call_files() + self.assertEqual(files, { + 'files[%s]' % image_filename: (image_filename, image_data, "image/png"), # the named one + 'files[]': ('', image_data, "image/png"), # the unnamed one + }) + + 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() + data = self.get_api_call_data() + self.assertNotIn('cc', data) + self.assertNotIn('ccname', data) + self.assertNotIn('bcc', data) + self.assertNotIn('bccname', data) + headers = json.loads(data['headers']) + self.assertNotIn('Reply-To', headers) + + # 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() + data = self.get_api_call_data() + self.assertNotIn('to', data) + self.assertNotIn('toname', data) + + def test_api_failure(self): + self.set_mock_response(status_code=400) + with self.assertRaises(AnymailAPIError): + sent = mail.send_mail('Subject', 'Body', 'from@example.com', ['to@example.com']) + self.assertEqual(sent, 0) + + # Make sure fail_silently is respected + self.set_mock_response(status_code=400) + sent = mail.send_mail('Subject', 'Body', 'from@example.com', ['to@example.com'], fail_silently=True) + self.assertEqual(sent, 0) + + def test_api_error_includes_details(self): + """AnymailAPIError should include ESP's error message""" + # JSON error response: + error_response = b"""{ + "message": "error", + "errors": [ + "Helpful explanation from SendGrid", + "and more" + ] + }""" + self.set_mock_response(status_code=200, raw=error_response) + with self.assertRaisesRegex(AnymailAPIError, + r"\bHelpful explanation from SendGrid\b.*and more\b"): + self.message.send() + + # Non-JSON error response: + self.set_mock_response(status_code=500, raw=b"Ack! Bad proxy!") + with self.assertRaisesMessage(AnymailAPIError, "Ack! Bad proxy!"): + self.message.send() + + # No content in the error response: + self.set_mock_response(status_code=502, raw=None) + with self.assertRaises(AnymailAPIError): + self.message.send() + + +class SendGridBackendAnymailFeatureTests(SendGridBackendMockAPITestCase): + """Test backend support for Anymail added features""" + + def test_metadata(self): + # Note: SendGrid doesn't handle complex types in metadata + self.message.metadata = {'user_id': "12345", 'items': 6} + self.message.send() + smtpapi = self.get_smtpapi() + self.assertEqual(smtpapi['unique_args'], {'user_id': "12345", 'items': 6}) + + def test_send_at(self): + utc_plus_6 = get_fixed_timezone(6 * 60) + utc_minus_8 = get_fixed_timezone(-8 * 60) + + 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() + smtpapi = self.get_smtpapi() + self.assertEqual(smtpapi['send_at'], timegm((2016, 3, 4, 13, 6, 7))) # 05:06 UTC-8 == 13:06 UTC + + # Timezone-naive datetime assumed to be Django current_timezone + self.message.send_at = datetime(2022, 10, 11, 12, 13, 14, 567) # microseconds should get stripped + self.message.send() + smtpapi = self.get_smtpapi() + self.assertEqual(smtpapi['send_at'], timegm((2022, 10, 11, 6, 13, 14))) # 12:13 UTC+6 == 06:13 UTC + + # Date-only treated as midnight in current timezone + self.message.send_at = date(2022, 10, 22) + self.message.send() + smtpapi = self.get_smtpapi() + self.assertEqual(smtpapi['send_at'], timegm((2022, 10, 21, 18, 0, 0))) # 00:00 UTC+6 == 18:00-1d UTC + + # POSIX timestamp + self.message.send_at = 1651820889 # 2022-05-06 07:08:09 UTC + self.message.send() + smtpapi = self.get_smtpapi() + self.assertEqual(smtpapi['send_at'], 1651820889) + + def test_tags(self): + self.message.tags = ["receipt", "repeat-user"] + self.message.send() + smtpapi = self.get_smtpapi() + self.assertCountEqual(smtpapi['category'], ["receipt", "repeat-user"]) + + def test_tracking(self): + # Test one way... + self.message.track_clicks = False + self.message.track_opens = True + self.message.send() + smtpapi = self.get_smtpapi() + self.assertEqual(smtpapi['filters']['clicktrack'], {'settings': {'enable': 0}}) + self.assertEqual(smtpapi['filters']['opentrack'], {'settings': {'enable': 1}}) + + # ...and the opposite way + self.message.track_clicks = True + self.message.track_opens = False + self.message.send() + smtpapi = self.get_smtpapi() + self.assertEqual(smtpapi['filters']['clicktrack'], {'settings': {'enable': 1}}) + self.assertEqual(smtpapi['filters']['opentrack'], {'settings': {'enable': 0}}) + + 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() + data = self.get_api_call_data() + self.assertNotIn('x-smtpapi', data) + + def test_esp_extra(self): + self.message.tags = ["tag"] + self.message.esp_extra = { + 'x-smtpapi': {'asm_group_id': 1}, + 'newthing': "some param not supported by Anymail", + } + self.message.send() + # Additional send params: + data = self.get_api_call_data() + self.assertEqual(data['newthing'], "some param not supported by Anymail") + # Should merge x-smtpapi + smtpapi = self.get_smtpapi() + self.assertEqual(smtpapi['category'], ["tag"]) + self.assertEqual(smtpapi['asm_group_id'], 1) + + # noinspection PyUnresolvedReferences + def test_send_attaches_anymail_status(self): + """ The anymail_status should be attached to the message when it is sent """ + # the DEFAULT_RAW_RESPONSE above is the *only* success response SendGrid returns, + # so no need to override it here + 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.assertRegex(msg.anymail_status.message_id, r'\<.+@example\.com\>') # don't know exactly what it'll be + self.assertEqual(msg.anymail_status.recipients['to1@example.com'].status, 'queued') + self.assertEqual(msg.anymail_status.recipients['to1@example.com'].message_id, + msg.anymail_status.message_id) + self.assertEqual(msg.anymail_status.esp_response.content, self.DEFAULT_RAW_RESPONSE) + + # noinspection PyUnresolvedReferences + def test_send_failed_anymail_status(self): + """ If the send fails, anymail_status should contain initial values""" + self.set_mock_response(status_code=500) + 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 a non-JSON API response, should raise an API exception""" + mock_response = self.set_mock_response(status_code=200, + raw=b"yikes, this isn't a real response") + 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, mock_response) + + def test_json_serialization_errors(self): + """Try to provide more information about non-json-serializable data""" + self.message.metadata = {'total': Decimal('19.99')} + with self.assertRaises(AnymailSerializationError) as cm: + self.message.send() + print(self.get_api_call_data()) + err = cm.exception + self.assertIsInstance(err, TypeError) # compatibility with json.dumps + self.assertIn("Don't know how to send this data to SendGrid", str(err)) # our added context + self.assertIn("Decimal('19.99') is not JSON serializable", str(err)) # original message + + +class SendGridBackendRecipientsRefusedTests(SendGridBackendMockAPITestCase): + """Should raise AnymailRecipientsRefused when *all* recipients are rejected or invalid""" + + # SendGrid doesn't check email bounce or complaint lists at time of send -- + # it always just queues the message. You'll need to listen for the "rejected" + # and "failed" events to detect refused recipients. + + pass + + +@override_settings(ANYMAIL_SEND_DEFAULTS={ + 'metadata': {'global': 'globalvalue', 'other': 'othervalue'}, + 'tags': ['globaltag'], + 'track_clicks': True, + 'track_opens': True, + 'esp_extra': {'globaloption': 'globalsetting'}, +}) +class SendGridBackendSendDefaultsTests(SendGridBackendMockAPITestCase): + """Tests backend support for global SEND_DEFAULTS""" + + def test_send_defaults(self): + """Test that global send defaults are applied""" + self.message.send() + data = self.get_api_call_data() + smtpapi = self.get_smtpapi() + # All these values came from ANYMAIL_SEND_DEFAULTS: + self.assertEqual(smtpapi['unique_args'], {'global': 'globalvalue', 'other': 'othervalue'}) + self.assertEqual(smtpapi['category'], ['globaltag']) + self.assertEqual(smtpapi['filters']['clicktrack']['settings']['enable'], 1) + self.assertEqual(smtpapi['filters']['opentrack']['settings']['enable'], 1) + self.assertEqual(data['globaloption'], 'globalsetting') + + def test_merge_message_with_send_defaults(self): + """Test that individual message settings are *merged into* the global send defaults""" + self.message.metadata = {'message': 'messagevalue', 'other': 'override'} + self.message.tags = ['messagetag'] + self.message.track_clicks = False + self.message.esp_extra = {'messageoption': 'messagesetting'} + + self.message.send() + data = self.get_api_call_data() + smtpapi = self.get_smtpapi() + # All these values came from ANYMAIL_SEND_DEFAULTS + message.*: + self.assertEqual(smtpapi['unique_args'], { + 'global': 'globalvalue', + 'message': 'messagevalue', # additional metadata + 'other': 'override', # override global value + }) + self.assertCountEqual(smtpapi['category'], ['globaltag', 'messagetag']) # tags concatenated + self.assertEqual(smtpapi['filters']['clicktrack']['settings']['enable'], 0) # message overrides + self.assertEqual(smtpapi['filters']['opentrack']['settings']['enable'], 1) + self.assertEqual(data['globaloption'], 'globalsetting') + self.assertEqual(data['messageoption'], 'messagesetting') # additional esp_extra + + @override_settings(ANYMAIL_SENDGRID_SEND_DEFAULTS={ + 'tags': ['esptag'], + 'metadata': {'esp': 'espvalue'}, + 'track_opens': False, + }) + def test_esp_send_defaults(self): + """Test that ESP-specific send defaults override individual global defaults""" + self.message.send() + data = self.get_api_call_data() + smtpapi = self.get_smtpapi() + # All these values came from ANYMAIL_SEND_DEFAULTS plus ANYMAIL_SENDGRID_SEND_DEFAULTS: + self.assertEqual(smtpapi['unique_args'], {'esp': 'espvalue'}) # entire metadata overridden + self.assertCountEqual(smtpapi['category'], ['esptag']) # entire tags overridden + self.assertEqual(smtpapi['filters']['clicktrack']['settings']['enable'], 1) # no override + self.assertEqual(smtpapi['filters']['opentrack']['settings']['enable'], 0) # esp override + self.assertEqual(data['globaloption'], 'globalsetting') # we didn't override the global esp_extra + + +@override_settings(EMAIL_BACKEND="anymail.backends.sendgrid.SendGridBackend") +class SendGridBackendImproperlyConfiguredTests(SimpleTestCase, AnymailTestMixin): + """Test ESP backend without required settings in place""" + + def test_missing_api_key(self): + with self.assertRaises(ImproperlyConfigured) as cm: + mail.send_mail('Subject', 'Message', 'from@example.com', ['to@example.com']) + errmsg = str(cm.exception) + self.assertRegex(errmsg, r'\bSENDGRID_API_KEY\b') + self.assertRegex(errmsg, r'\bANYMAIL_SENDGRID_API_KEY\b') diff --git a/anymail/tests/test_sendgrid_integration.py b/anymail/tests/test_sendgrid_integration.py new file mode 100644 index 0000000..088ae57 --- /dev/null +++ b/anymail/tests/test_sendgrid_integration.py @@ -0,0 +1,96 @@ +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 sample_image_content, AnymailTestMixin + + +SENDGRID_TEST_API_KEY = os.getenv('SENDGRID_TEST_API_KEY') + + +@unittest.skipUnless(SENDGRID_TEST_API_KEY, + "Set SENDGRID_TEST_API_KEY environment variable " + "to run SendGrid integration tests") +@override_settings(ANYMAIL_SENDGRID_API_KEY=SENDGRID_TEST_API_KEY, + EMAIL_BACKEND="anymail.backends.sendgrid.SendGridBackend") +class SendGridBackendIntegrationTests(SimpleTestCase, AnymailTestMixin): + """SendGrid API integration tests + + These tests run against the **live** SendGrid API, using the + environment variable `SENDGRID_TEST_API_KEY` as the API key + If those variables are not set, these tests won't run. + + SendGrid 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 SendGrid's "sink domain" @sink.sendgrid.net. + https://support.sendgrid.com/hc/en-us/articles/201995663-Safely-Test-Your-Sending-Speed + + """ + + def setUp(self): + super(SendGridBackendIntegrationTests, self).setUp() + self.message = AnymailMessage('Anymail SendGrid integration test', 'Text content', + 'from@example.com', ['to@sink.sendgrid.net']) + self.message.attach_alternative('

HTML content

', "text/html") + + def test_simple_send(self): + # Example of getting the SendGrid send status and message 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@sink.sendgrid.net'].status + message_id = anymail_status.recipients['to@sink.sendgrid.net'].message_id + + self.assertEqual(sent_status, 'queued') # SendGrid always queues + self.assertRegex(message_id, r'\<.+@example\.com/>') # should use from_email's domain + 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().replace(microsecond=0) + timedelta(minutes=2) + message = AnymailMessage( + subject="Anymail all-options integration test FILES", + body="This is the text body", + from_email="Test From ", + to=["to1@sink.sendgrid.net", "Recipient 2 "], + cc=["cc1@sink.sendgrid.net", "Copy 2 "], + bcc=["bcc1@sink.sendgrid.net", "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", "tag 2"], + 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(sample_image_content()) + message.attach_alternative( + "

HTML: with link" + "and image: " % cid, + "text/html") + + message.send() + self.assertEqual(message.anymail_status.status, {'queued'}) # SendGrid always queues + message_id = message.anymail_status.message_id + print(message_id) + + @override_settings(ANYMAIL_SENDGRID_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, 400) + # Make sure the exception message includes SendGrid's response: + self.assertIn("authorization grant is invalid", str(err)) diff --git a/docs/esps/sendgrid.rst b/docs/esps/sendgrid.rst index 1e727a1..9ae65fb 100644 --- a/docs/esps/sendgrid.rst +++ b/docs/esps/sendgrid.rst @@ -1,17 +1,128 @@ -.. _sendgrid: +.. _sendgrid-backend: SendGrid --------- +======== -.. note:: +Anymail integrates with the `SendGrid`_ email service, +using their `Web API v2`_. (Their v3 API does not support sending mail, +but the v3 API calls *do* get information about mail sent through v2.) - SendGrid support is being developed now +.. _SendGrid: https://sendgrid.com/ +.. _Web API v2: https://sendgrid.com/docs/API_Reference/Web_API/mail.html Settings -======== +-------- - EMAIL_BACKEND = "anymail.backends.sendgrid.SendGridBackend" -(Watch your capitalization: SendGrid spells their name with an -uppercase "G", so Anymail does too.) +.. rubric:: EMAIL_BACKEND + +To use Anymail's SendGrid backend, set: + + .. code-block:: python + + EMAIL_BACKEND = "anymail.backends.sendgrid.SendGridBackend" + +in your settings.py. (Watch your capitalization: SendGrid spells +their name with an uppercase "G", so Anymail does too.) + + +.. setting:: ANYMAIL_SENDGRID_API_KEY + +.. rubric:: SENDGRID_API_KEY + +Required. A SendGrid API key with "Mail Send" permission. +(Manage API keys in your `SendGrid API key settings`_. +Anymail does not support SendGrid's earlier username/password +authentication.) + + .. code-block:: python + + ANYMAIL = { + ... + "SENDGRID_API_KEY": "", + } + +Anymail will also look for ``SENDGRID_API_KEY`` at the +root of the settings file if neither ``ANYMAIL["SENDGRID_API_KEY"]`` +nor ``ANYMAIL_SENDGRID_API_KEY`` is set. + +.. _SendGrid API key settings: https://app.sendgrid.com/settings/api_keys + + +.. setting:: ANYMAIL_SENDGRID_API_URL + +.. rubric:: SENDGRID_API_URL + +The base url for calling the SendGrid v2 API. + +The default is ``SENDGRID_API_URL = "https://api.sendgrid.com/api/"`` +(It's unlikely you would need to change this.) + + +esp_extra support +----------------- + +To use SendGrid features not directly supported by Anymail, you can +set a message's :attr:`~anymail.message.AnymailMessage.esp_extra` to +a `dict` of parameters for SendGrid's `mail.send API`_. Any keys in +your :attr:`esp_extra` dict will override Anymail's normal values +for that parameter, except that `'x-smtpapi'` will be merged. + +Example: + + .. code-block:: python + + message.esp_extra = { + 'x-smtpapi': { + "asm_group": 1, # Assign SendGrid unsubscribe group for this message + "asm_groups_to_display": [1, 2, 3] + } + } + + +(You can also set `"esp_extra"` in Anymail's +:ref:`global send defaults ` to apply it to all +messages.) + + +.. _mail.send API: https://sendgrid.com/docs/API_Reference/Web_API/mail.html#-send + + + +Limitations and quirks +---------------------- + +**Duplicate attachment filenames** + Anymail is not capable of communicating multiple attachments with + the same filename to SendGrid. (This also applies to multiple attachments + with *no* filename, though not to inline images.) + + If you are sending multiple attachments on a single message, + make sure each one has a unique, non-empty filename. + + +**Message-ID** + SendGrid does not return any sort of unique id from its send API call. + Knowing a sent message's ID can important for later queries about + the message's status. + + To work around this, Anymail generates a new Message-ID for each + outgoing message, provides it to SendGrid, and includes it in the + :attr:`~anymail.message.AnymailMessage.anymail_status` + attribute after you send the message. + + In later SendGrid API calls, you can match that Message-ID + to SendGrid's ``smtp-id`` event field. + + Anymail will use the domain of the message's :attr:`from_email` + to generate the Message-ID. (If this isn't desired, you can supply + your own Message-ID in the message's :attr:`extra_headers`.) + + +**Invalid Addresses** + SendGrid will accept *and send* just about anything as + a message's :attr:`from_email`. (And email protocols are + actually OK with that.) + + (Tested March, 2016) diff --git a/setup.py b/setup.py index 392adb3..b85287a 100644 --- a/setup.py +++ b/setup.py @@ -35,6 +35,7 @@ setup( extras_require={ "mailgun": ["requests>=2.4.3"], "mandrill": ["requests>=1.0.0"], + "sendgrid": ["requests>=2.4.3"], }, include_package_data=True, test_suite="runtests.runtests",