Update chapter-16.rst

nicozanf · Jul 7, 2024 · ef45784 · ef45784
1 parent f7b4310
commit ef45784
Showing 1 changed file with 73 additions and 0 deletions.
diff --git a/docs/chapter-16.rst b/docs/chapter-16.rst
@@ -73,6 +73,79 @@ To prevent database locks (in particular with sqlite) we recommend:
        except Exception:
            db.rollback()
 
+
+Sending messages using a background task
+----------------------------------------
+
+As en example of application of the above,
+Consider the case of wanting to send emails asynchronously from a background task.
+In this example we send them using SendGrid from Twilio (https://www.twilio.com/docs/sendgrid/for-developers/sending-email/quickstart-python)
+Also we assume emails are represented by the following JSON structure
+
+That means you need a new task:
+
+.. code:: python
+
+    import sendgrid
+    from sendgrid.helpers.mail import Mail, Email, To, Content
+
+    def sendmail_task(from_addr, to_addrs, subject, body):
+        ""
+        # build the messages using sendgrid API
+        from_email = Email(from_addr)  # Must be your verified sender
+        content_type = "text/plain" if body[:6] != "<html>" else "text/html"
+        content = Content(content_type, body)
+        mail = Mail(from_email, To(to_addrs), subject, content)
+        # ask sendgrid to deliver it
+        sg = sendgrid.SendGridAPIClient(api_key=settings.SENDGRID_API_KEY)
+        response = sg.client.mail.send.post(request_body=mail.get())
+        # check if worked
+        assert response.status_code == "200"
+
+    # register the above task with the scheduler
+    scheduler.register_task("sendmail", sendmail_task)
+
+
+To schedule sending a new email do:
+
+.. code:: python
+
+    email = {
+        "from_addr": "[email protected]",
+        "to_addrs": ["[email protected]"], 
+        "subject": "Hello World",
+        "body": "I am alive!",
+    }
+    scheduler.enqueue_run(name="sendmail", inputs=email, scheduled_for=None)
+
+The key:value in the email representation must match the arguments of the task.
+The ``scheuled_for`` argument is optional and allows you to specify when the email should be sent.
+You can use the Dashboard to see the status of your ``task_run``s for the task called ``sendmail``.
+
+You can also tell auth to tap into above mechanism for sending emails:
+
+.. code:: python
+
+    class MySendGridSender:
+        def __init__(self, from_addr):
+            self.from_addr = from_adds
+        def send(self, to_addr, subject, body):
+            email = {
+                "from_addr": self.from_addr,
+                "to_addrs": [to_addr], 
+                "subject": subject,
+                "body": body,
+            }
+            scheduler.enqueue_run(name="sendmail", inputs=email)
+
+    auth.sender = MySendGridSender(from_addr="[email protected]")
+
+With the above, Auth will not send emails using smtplib. Instead it will send them with SendGrid using the scheduler.
+Notice the only requirement here is that ``auth.sender`` must be an object with a ``send`` method with the same signature as in the example.
+
+Notice, it it also possible to send SMS messages instead of emails but this requires 1) store the phone number in ``auth_user`` and 2) override the ``Auth.send`` method.
+
+
 Celery
 ------