Merge pull request #10 from level12/9-accept-additional-mail-options

Add ability to insert additional mail options for mailgun

Author: guruofgentoo

README.rst

@@ -16,7 +16,7 @@ Usage
   $ pip install keg-mail
 
 
-Initialize Keg-Mail in you application
+Initialize Keg-Mail in your application
 
 .. code::
 
@@ -65,8 +65,8 @@ Send the email
 
   bp.route('/')
   def index():
-      mail.send(
-          'you@something.com'
+      mail.send_email(
+          'you@something.com',
           keg_mail.Email(
             subject="Hello {name}!",
             content=emails.hello_world_content,
@@ -86,3 +86,21 @@ Test the email
           assert len(outbox) == 1
           assert outbox[0].subject == "Hello You!"
           assert outbox[0].body == "Hello You!"
+
+
+Mailgun-specific options
+------------------------
+
+Mailgun supports various options such as tagging, user-defined variables, etc.
+These can be added via a ``mailgun_opts`` dictionary that can be passed to the
+app's mail engine's ``send`` method directly:
+
+.. code::
+
+    flask.current_app.mail.send(
+        msg,
+        mailgun_opts={
+            'v:user_name': 'John Doe',
+            'v:user_id': 100,
+        },
+    )

keg_mail/content.py

@@ -27,7 +27,7 @@ def escape_html(content):
     return EmailContent(html=_escape_html(content), text=content)
 
 
-def send_email(recipient, email):
+def send_email(recipient, email, **kwargs):
     """Sends an `Email` to a recipient.
 
     :param recipient: is an email address.
@@ -49,7 +49,7 @@ def send_email(recipient, email):
     )
 
     try:
-        mail_engine.send(message)
+        mail_engine.send(message, **kwargs)
     except (socket.gaierror, socket.error):  # pragma: no cover
         raise SendEmailError('SMTP Connection error')
     except smtplib.SMTPAuthenticationError:  # pragma: no cover

keg_mail/mailgun.py

@@ -117,7 +117,7 @@ def _ensure_unique_recipients(self, to: List[str], cc: List[str], bcc: List[str]
 
         return list(to), list(cc), list(bcc)
 
-    def send(self, message: flask_mail.Message):
+    def send(self, message: flask_mail.Message, mailgun_opts: Dict = None):
         to, cc, bcc = self._ensure_unique_recipients(
             ensure_list(message.recipients),
             ensure_list(message.cc),
@@ -136,6 +136,8 @@ def send(self, message: flask_mail.Message):
             'o:testmode': 'yes' if self.testing else 'no'
         }
 
+        request_body.update(mailgun_opts or {})
+
         files = None
         if message.attachments:
             files = [

keg_mail/plugin.py

@@ -18,8 +18,8 @@
 
 
 class _MailMixin(flask_mail._MailMixin):
-    def mailgun_send(self, message):
-        return self.mailgun_client.send(message)
+    def mailgun_send(self, message, mailgun_opts=None):
+        return self.mailgun_client.send(message, mailgun_opts)
 
     def mailgun_sync_webhooks(self):
         return self.mailgun_client.sync_webhooks(self.mailgun_webhooks)
@@ -55,9 +55,10 @@ def mailgun_update_message_status(self, event_data):
             return
         self.mailgun_client.update_message_status(event_data)
 
-    def send(self, message):
+    def send(self, message, **kwargs):
         if self.mailgun_client:
-            return self.mailgun_send(message)
+            mailgun_opts = kwargs.pop('mailgun_opts', None)
+            return self.mailgun_send(message, mailgun_opts)
 
         if message.extra_headers is None:
             message.extra_headers = {}

keg_mail/tests/test_mailgun.py

@@ -53,6 +53,31 @@ def test_send(self, requests_mock):
         assert body['html'] == ['<blink>very important message</blink>']
         assert 'attachment' not in body
 
+    def test_send_with_mailgun_opts(self, requests_mock):
+        requests_mock.post('https://api.mailgun.net/v3/example.com/messages',
+                           json={'response': 'ok'})
+
+        client = MailgunClient(domain='example.com', api_key='foo', testing=False)
+        message = flask_mail.Message(
+            subject='RE: xyz',
+            recipients=['bob@example.com', 'joe@example.com'],
+            body='very important message',
+            html='<blink>very important message</blink>',
+        )
+        mailgun_opts = {'o:tag': ['one_tag', 'another_tag']}
+        resp = client.send(message, mailgun_opts=mailgun_opts)
+
+        assert resp == {'response': 'ok'}
+
+        assert requests_mock.call_count == 1
+
+        req = requests_mock.request_history[0]
+        body = urllib.parse.parse_qs(req.text)
+
+        assert body['to'] == ['bob@example.com', 'joe@example.com']
+        assert body['o:tag'] == ['one_tag', 'another_tag']
+        assert 'attachment' not in body
+
     def test_send_attachments(self, requests_mock):
         requests_mock.post('https://api.mailgun.net/v3/example.com/messages',
                            json={'response': 'ok'})

keg_mail/tests/test_plugin.py

@@ -0,0 +1,60 @@
+from unittest import mock
+
+import flask_mail
+
+from keg_mail.mailgun import MailgunClient
+from keg_mail.plugin import _MailMixin
+
+
+def mock_patch(*args, **kwargs):
+    kwargs.setdefault('autospec', False)
+    kwargs.setdefault('spec_set', False)
+    return mock.patch(*args, **kwargs)
+
+
+class TestKegMailMixin:
+    def setup_method(self):
+        client = MailgunClient(domain="keg.example.com", api_key="foo", testing=True)
+        self.plugin = _MailMixin()
+        self.plugin.mailgun_client = client
+        self.message = flask_mail.Message(
+            subject="binford tools",
+            recipients=["bob@example.com", "joe@example.com"],
+            body="more power",
+            html="<blink>more power</blink>",
+            sender="no-reply@binford.com",
+            cc=["tim@example.com"],
+            bcc=["al@example.com"],
+        )
+
+    @mock_patch("keg_mail.mailgun.MailgunClient.send")
+    def test_mailgun_send_no_options(self, m_send):
+        self.plugin.mailgun_send(self.message)
+        assert m_send.call_args[0][0] is self.message
+        assert not m_send.call_args[0][1]
+
+    @mock_patch("keg_mail.mailgun.MailgunClient.send")
+    def test_mailgun_send_with_options(self, m_send):
+        mailgun_opt = {'opt1': 'bar'}
+        self.plugin.mailgun_send(self.message, mailgun_opts=mailgun_opt)
+        assert m_send.call_args[0][0] is self.message
+        assert m_send.call_args[0][1] == mailgun_opt
+
+    @mock_patch("keg_mail.plugin._MailMixin.mailgun_send")
+    def test_plugin_send_mailgun_client_no_options(self, m_send):
+        self.plugin.send(self.message)
+        assert m_send.call_args[0][0] is self.message
+        assert not m_send.call_args[0][1]
+
+    @mock_patch("keg_mail.plugin._MailMixin.mailgun_send")
+    def test_plugin_send_mailgun_client_with_options(self, m_send):
+        mailgun_opt = {'opt1': 'bar'}
+        self.plugin.send(self.message, mailgun_opts=mailgun_opt)
+        assert self.message is m_send.call_args[0][0]
+        assert m_send.call_args[0][1] == mailgun_opt
+
+    @mock_patch("keg_mail.plugin._MailMixin.mailgun_send")
+    def test_plugin_send_no_mailgun_client(self, m_send):
+        self.plugin.mailgun_client = None
+        self.plugin.send(self.message)
+        assert not m_send.called