From 217ca5be4e18ddb1109028fc77682ba7bf437c1d Mon Sep 17 00:00:00 2001
From: Mike Hillyer <mike@kumomta.com>
Date: Mon, 8 May 2023 18:23:15 -0400
Subject: [PATCH] Add http API call routing to Policy Chapter.

---
 docs/generate-toc.py             |  1 +
 docs/userguide/policy/http.md    | 55 ++++++++++++++++++++++++++++++++
 docs/userguide/policy/routing.md |  2 +-
 3 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 docs/userguide/policy/http.md

diff --git a/docs/generate-toc.py b/docs/generate-toc.py
index 35e779e4..bbb065b4 100755
--- a/docs/generate-toc.py
+++ b/docs/generate-toc.py
@@ -208,6 +208,7 @@ TOC = [
                         "Advanced Tenant to Pool Mapping",
                         "userguide/policy/tenantpool.md",
                     ),
+                    Page("Routing Messages via HTTP Request", "userguide/policy/http.md"),
                 ],
             ),
         ],
diff --git a/docs/userguide/policy/http.md b/docs/userguide/policy/http.md
new file mode 100644
index 00000000..d029c8f1
--- /dev/null
+++ b/docs/userguide/policy/http.md
@@ -0,0 +1,55 @@
+# Routing Messages Via HTTP Request
+
+Some sending environments use a mixture of different services to send messages, and while it's possible to relay messages through many services using SMTP, some services are only/better served via an HTTP API.
+
+The following example shows how to send a queued message via custom lua, in this case assembling and API call and sending it to a third-part SMTP API relay provider.
+
+```lua
+kumo.on('make.mailgun', function(domain, tenant, campaign)
+  local client = kumo.http.build_client {}
+  local sender = { }
+
+  function sender:send(message)
+    local request = client:post 'https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages.mime'
+
+    request:basic_auth('api', 'YOUR_API_KEY')
+    request:form_multipart_data {
+      to = message:recipient(),
+      message = message:get_data()
+    }
+
+    -- Make the request
+    local response = request:send()
+
+    -- and handle the result
+    local disposition = string.format(
+      '%d %s %s',
+      response:status_code(),
+      response:status_reason(),
+      response:text()
+    )
+    if response:status_is_success() then
+      -- Success!
+      return disposition
+    end
+
+    -- Failed!
+    kumo.reject(400, disposition)
+  end
+  return sender
+end)
+
+kumo.on('get_queue_config', function(domain, tenant, campaign)
+  if tenant == 'mailgun-user' then
+    return kumo.make_queue_config {
+      protocol = {
+        custom_lua = {
+          constructor = 'make.mailgun',
+        },
+      },
+    }
+  end
+
+  return kumo.make_queue_config {}
+end)
+```
diff --git a/docs/userguide/policy/routing.md b/docs/userguide/policy/routing.md
index 774cde0d..ab6d8e4d 100644
--- a/docs/userguide/policy/routing.md
+++ b/docs/userguide/policy/routing.md
@@ -6,7 +6,7 @@ If you need to "smarthost" or route messages through another server, you can do
 msg:set_meta('queue', 'imap.server.hostname')
 ```
 
-This should me located in a 'smtp_server_message_received' function like this:
+This should be located in a 'smtp_server_message_received' function like this:
 
 ```lua
 kumo.on('smtp_server_message_received', function(msg)