From 906544c3f9206f5ac419a633695fc230213455f4 Mon Sep 17 00:00:00 2001
From: Jeppe Larsen <jwl@sysctl.dk>
Date: Mon, 1 Feb 2021 10:46:52 +0100
Subject: [PATCH 1/3] Add callback_url and userref for email requests.
 Re-arrange arguments

---
 docs/rest.rst | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/docs/rest.rst b/docs/rest.rst
index 0801414..079284b 100644
--- a/docs/rest.rst
+++ b/docs/rest.rst
@@ -1525,17 +1525,19 @@ If you need SPF on your domain, you will need to include the following in your D
    :<json string subject: The subject line of the email, tags can be used like in the message to personalise the subject.
    :<json string from: The name and email of the sender, can be just the email if no name is specified, see below for format.
    :<json string reply: The name and email of the sender, can be just the email if no name is specified, see below for format.
+   :<json string callback_url: Callback URL to get status reports.
+   :<json string userref: Add your own custom reference to be passed back to the provided callback URL.
+   :<json array recipients: list of email addresses to receive the email, described below:
+   :<jsonarr string address: The recipient email address.
+   :<jsonarr string name: The name of the recipient shown in the email client.
+   :<jsonarr array tagvalues: A list of string values corresponding to the tags in the email. The order and amount of tag values must exactly match the tags.
+   :<jsonarr array cc: A list of cc recipients, taks an address and optionally a name of the recipient.
+   :<jsonarr array bcc: A list of cc recipients, taks an address and optionally a name of the recipient.
    :<json array tags: A list of string tags, which will be replaced with the tag values for each recipient, if used remember to also add tagvalues to all recipients.
    :<json array attachments: A list of base64 encoded files to be attached to the email, described below:
-   :<json string data: The base64 encoded data of the file to attach.
-   :<json string filename: The name of the file attached to the email.
-   :<json string mimetype: The mimetype of the file, eg. text/csv.
-   :<json array recipients: list of email addresses to receive the email, described below:
-   :<json string address: The recipient email address.
-   :<json string name: The name of the recipient shown in the email client.
-   :<json array tagvalues: A list of string values corresponding to the tags in the email. The order and amount of tag values must exactly match the tags.
-   :<json array cc: A list of cc recipients, taks an address and optionally a name of the recipient.
-   :<json array bcc: A list of cc recipients, taks an address and optionally a name of the recipient.
+   :<jsonarr string data: The base64 encoded data of the file to attach.
+   :<jsonarr string filename: The name of the file attached to the email.
+   :<jsonarr string mimetype: The mimetype of the file, eg. text/csv.
    :status 200: Returns a dict with an array of message IDs and a dictionary with usage information on success
    :status 400: Ie. invalid arguments, details in the JSON body
    :status 401: Ie. invalid API key or signature
@@ -1587,7 +1589,7 @@ If you need SPF on your domain, you will need to include the following in your D
                431332671
            ]
            "usage": {
-               "amount": 1,
+               "amount": 4,
                "currency": "DKK",
                "total_cost": 0.003
            }

From fe66f263cedc5c14dc8e146f54e884c9e8f5ab78 Mon Sep 17 00:00:00 2001
From: Jeppe Larsen <jwl@sysctl.dk>
Date: Mon, 1 Feb 2021 11:24:16 +0100
Subject: [PATCH 2/3] Seperate attachments docs out in seperate section

---
 docs/rest.rst | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/docs/rest.rst b/docs/rest.rst
index 079284b..f91f521 100644
--- a/docs/rest.rst
+++ b/docs/rest.rst
@@ -1527,17 +1527,13 @@ If you need SPF on your domain, you will need to include the following in your D
    :<json string reply: The name and email of the sender, can be just the email if no name is specified, see below for format.
    :<json string callback_url: Callback URL to get status reports.
    :<json string userref: Add your own custom reference to be passed back to the provided callback URL.
+   :<json array tags: A list of string tags, which will be replaced with the tag values for each recipient, if used remember to also add tagvalues to all recipients.
    :<json array recipients: list of email addresses to receive the email, described below:
    :<jsonarr string address: The recipient email address.
    :<jsonarr string name: The name of the recipient shown in the email client.
    :<jsonarr array tagvalues: A list of string values corresponding to the tags in the email. The order and amount of tag values must exactly match the tags.
    :<jsonarr array cc: A list of cc recipients, taks an address and optionally a name of the recipient.
    :<jsonarr array bcc: A list of cc recipients, taks an address and optionally a name of the recipient.
-   :<json array tags: A list of string tags, which will be replaced with the tag values for each recipient, if used remember to also add tagvalues to all recipients.
-   :<json array attachments: A list of base64 encoded files to be attached to the email, described below:
-   :<jsonarr string data: The base64 encoded data of the file to attach.
-   :<jsonarr string filename: The name of the file attached to the email.
-   :<jsonarr string mimetype: The mimetype of the file, eg. text/csv.
    :status 200: Returns a dict with an array of message IDs and a dictionary with usage information on success
    :status 400: Ie. invalid arguments, details in the JSON body
    :status 401: Ie. invalid API key or signature
@@ -1565,13 +1561,18 @@ If you need SPF on your domain, you will need to include the following in your D
           "plaintext": "Hello %firsname %surname %target is about to be removed.",
           "subject": "Annihilation: %target",
           "from": "Darth Vader <darth@example.com>",
-          "returnpath": "bounce@example.com",
+          "reply": "bounce@example.com",
           "tags": ["%firstname", "%surname", '%target'],
           "recipients": [
               {"address": "l.organa@example.com", "name": "Leia Organa", "tagvalues": ["Leia", "Organa", "Alderaan"], "cc": [{"address": "h.solo@example.com", "name": "Han Solo"}], "bcc": [{"address": "chewie@example.com", "name": "Chewbacca"}]},
               {"address": "l.skywalker@example.com", "name": "Luke Skywalker", "tagvalues": ["Luke", "Skywalker", "Alderaan"] }
           ]
-      }
+          "attachments": [{
+            "data": "/9j/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCg"
+                    "sOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/yQALCAABAAEBAREA/8wABgAQEAX/2gAIAQEA"
+                    "AD8A0s8g/9k=",
+            "filename": "kyber.jpeg", "mimetype": "image/jpeg"}]
+          }
 
 
    **Example response**
@@ -1596,6 +1597,16 @@ If you need SPF on your domain, you will need to include the following in your D
 
        }
 
+If you want to send attachments, encode them as base64 add the following to the payload. The maximum *total* size for attachments is 5MB.
+
+.. http:post:: /rest/email
+   :synopsis: Add attachments.
+
+   :<json array attachments: A list of base64 encoded files to be attached to the email, described below:
+   :<jsonarr string data: The base64 encoded data of the file to attach.
+   :<jsonarr string filename: The name of the file attached to the email.
+   :<jsonarr string mimetype: The mimetype of the file, eg. text/csv.
+
 
 Email code examples
 ^^^^^^^^^^^^^^^^^^^

From dcaa7190619920cd89ac03efaa5db5a498398093 Mon Sep 17 00:00:00 2001
From: Jeppe Larsen <jwl@sysctl.dk>
Date: Tue, 2 Feb 2021 14:35:22 +0100
Subject: [PATCH 3/3] Add section about callback url for email

---
 docs/rest.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/docs/rest.rst b/docs/rest.rst
index f91f521..1622b18 100644
--- a/docs/rest.rst
+++ b/docs/rest.rst
@@ -1608,6 +1608,60 @@ If you want to send attachments, encode them as base64 add the following to the
    :<jsonarr string mimetype: The mimetype of the file, eg. text/csv.
 
 
+Email status callback
+^^^^^^^^^^^^^^^^^^^
+If you add a callback url to your email request, you will receive a callback with the following JSON payload. For more information about callbacks, see the `Webhooks`_  section.
+
+
+.. http:post:: /example/callback
+   :noindex:
+
+   Example of how our request to you could look like.
+
+   :<json integer id: The ID of the email this notification concerns
+   :<json integer time: The UNIX Timestamp for the delivery status event
+   :<json string email_address: The email address of the recipient
+   :<json string status: One of the states below, in all-caps, ie. DELIVERED
+   :<json string userref: If you specified a reference when sending the message, it's returned to you
+   :<json string details: If available, will contain extra information about the email with output from the SMTP server.
+   :<json string callback_url: The callback url provided
+   :status 200: If you reply with a 2xx code, we will consider the status delivered successfully.
+   :status 500: If we get a code >= 300, we will re-attempt delivery at a later time.
+
+   **Callback example**
+
+   .. sourcecode:: http
+
+      POST /example/callback HTTP/1.1
+      Host: example.com
+      Accept: */*
+      Content-Type: application/json
+
+      {
+          "id": 1000001,
+          "time": 1450000000,
+          "email_address": "example@test.com",
+          "status": "DELIVERED",
+          "userref": "foobar",
+          "details": "250 2.0.0 OK",
+          "callback_url": "https://example.com/example/callback",
+      }
+
+The status field can be of the follwing values.
+
+
+============= =========================================
+Status        Description
+============= =========================================
+PROCESSSED    The email has been successfully received by the system and is ready to be sent
+DELIVERED     The email was successfully delivered to the recipients inbox.
+DEFERRED      The email is delayed and will try to be sent at a later point. This typically happens if the recipients mailserver has a temporary issue.
+BOUNCED       The email could not be delivered. Typically when the address is unknown at the server.
+BLOCKED       The email has been blocked by the server.
+============= =========================================
+
+Depending on the error, the states `BLOCKED` and `BOUNCED` will have more information in the `details` field.
+
 Email code examples
 ^^^^^^^^^^^^^^^^^^^
 Code examples for sending emails.