chore: add docs for HTTP email delivery

docs/kratos/emails-sms/01_sending-emails-smtp.mdx

@@ -1,7 +1,7 @@
 ---
 id: sending-emails-smtp
-title: Use a custom SMTP server to send recovery and verification messages to users
-sidebar_label: SMTP server configuration
+title: Use a custom server to send recovery and verification messages to users
+sidebar_label: Email delivery configuration
 ---
 
 ```mdx-code-block
@@ -139,6 +139,92 @@ smtp://{YOUR_POSTMARK_SEVER_API_TOKEN}:{YOUR_POSTMARK_SEVER_API_TOKEN}@smtp.post
 # smtp://thetoken:[email protected]:587/
 ```
 
+## Send emails using an HTTP server
+
+Ory Identities supports sending emails using an HTTP server. This is useful if you want to customize the email content or use a
+service that doesn't provide an SMTP server.
+
+```mdx-code-block
+<Tabs groupId="console-or-cli-http-email">
+<TabItem value="cli" label="Ory CLI" default>
+```
+
+1. Download the Ory Identities config from your project and save it to a file:
+
+   ```shell
+   ## List all available projects
+   ory list projects
+
+   ## Get config
+   ory get identity-config {project-id} --format yaml > identity-config.yaml
+   ```
+
+2. Add the configuration for your custom HTTP server
+
+   ```yaml title="config.yml"
+   courier:
+     delivery_method: http
+     http:
+       request_config:
+         url: https://mail-sender.example.com
+         method: POST
+         body: base64://... # See below for the default payload and available variables
+         headers:
+           Content-Type: application/json
+         auth: # leave out, if your server doesn't require authentication, but note that we don't recommend that
+           type: basic_auth # or api_key
+           config:
+             username: my-username
+             password: my-password
+             # if you want to use an API key (type: api_key), use the following config instead:
+             # name: my-api-name
+             # value: my-api-key-value
+             # in: header # or cookie
+   ```
+
+3. Update the Ory Identities configuration using the file you worked with:
+
+   ```shell
+   ory update identity-config {project-id} --file updated_config.yaml
+   ```
+
+### Payload
+
+The payload of the HTTP request is a JSON object that's generated using a Jsonnet template. By default, the following payload is
+sent:
+
+```jsonnet
+function(ctx) {
+  recipient: ctx.Recipient,
+  template_type: ctx.TemplateType,
+  to: if "TemplateData" in ctx && "To" in ctx.TemplateData then ctx.TemplateData.To else null,
+  recovery_code: if "TemplateData" in ctx && "RecoveryCode" in ctx.TemplateData then ctx.TemplateData.RecoveryCode else null,
+  recovery_url: if "TemplateData" in ctx && "RecoveryURL" in ctx.TemplateData then ctx.TemplateData.RecoveryURL else null,
+  verification_url: if "TemplateData" in ctx && "VerificationURL" in ctx.TemplateData then ctx.TemplateData.VerificationURL else null,
+  verification_code: if "TemplateData" in ctx && "VerificationCode" in ctx.TemplateData then ctx.TemplateData.VerificationCode else null,
+  subject: ctx.Subject,
+  body: ctx.Body
+}
+```
+
+The courier passes the `Recipient`, `TemplateType`, and `TemplateData` variables into the Jsonnet template. These variables are
+available through the `ctx` object. `Recipient` will always be the email address of the user. `TemplateType` and the fields in
+`TemplateData` are linked in the following way with each template type containing the fields listed below:
+
+This will produce a JSON object, that contains all data available in the email. You can customize the payload
+
+```mdx-code-block
+</TabItem>
+<TabItem value="console" label="Ory Console (coming soon)" disabled>
+```
+
+The Ory Console doesn't support configuring this yet. Please use the Ory CLI instead.
+
+```mdx-code-block
+</TabItem>
+</Tabs>
+```
+
 ## Troubleshooting
 
 In general, if you have problems setting up email delivery, you can view outgoing messages on the **Monitoring** → **Email

docs/kratos/self-hosted/03_mail-courier-http.mdx

@@ -1,17 +1,17 @@
 ---
 id: email-http
-title: Mail API courier in self-hosted Ory Kratos
-sidebar_label: Sending emails
+title: HTTP based email delivery
+sidebar_label: Sending emails via HTTP API
 ---
 
-For sending Email by using an external mail provider instead of a local SMTP server, Ory Kratos can use a HTTP API (such as
-Mailchimp, your local mail sender, or your own microservice). Request method, headers, body, and content-type are fully
-configurable using options below.
+To send emails using an external mail provider instead of a local SMTP server, Ory Kratos can use an HTTP API (such as Mailchimp,
+your local mail sender, or your own microservice). Request method, headers, body, and content-type are fully configurable using
+the options below.
 
 ## Configuration
 
-Default configuration doesn't use API calls to send mail. To enable it you need to set the "delivery_strategy" flag to "http",
-sender URL, authorization (if needed) and request body format. (if needed) and request body format.
+By default, Ory Kratos doesn't use API calls to send mail. To enable it set the `delivery_strategy` configuration key to `http`,
+URL, authorization (if needed) and request body format.
 
 ### Request configuration
 
@@ -37,12 +37,12 @@ The configuration consists of:
 - `url` - the URL, which should be called (mandatory). It needs to be absolute, start with http:// or https:// scheme, and include
   path part - for example "https://api.sender.com/v1/message".
 - `method` - the HTTP method (GET, POST, ...) (mandatory)
-- `body` - URI of a JsonNet template, used to render the payload to send (optional). Use a `file://path/to/body.jsonnet` URL for
+- `body` - URI of a Jsonnet template, used to render the payload to send (optional). Use a `file://path/to/body.jsonnet` URL for
   referring to local files. This property is ignored for HTTP `method`s, which don't support sending of HTTP body payloads
   (TRACE).
 - `auth` - configuration of authentication and authorization mechanisms to be used by request
 
-Courier binds the `Recipient`, `TemplateType`, and `TemplateData` variables into the JsonNet template. These variables are
+The courier passes the `Recipient`, `TemplateType`, and `TemplateData` variables into the Jsonnet template. These variables are
 available through a `ctx` object. `Recipient` will always be the email address of the user. `TemplateType` and the fields in
 `TemplateData` are linked in the following way with each template type containing the fields listed below:
 
@@ -71,7 +71,7 @@ available through a `ctx` object. `Recipient` will always be the email address o
   - VerificationCode
   - Identity
 
-A universal jsonnet template to be sent to the mail provider endpoint would look like this:
+A universal Jsonnet template that works with all flows, would look like this:
 
 ```jsonnet
 function(ctx) {
@@ -87,28 +87,46 @@ function(ctx) {
 
 ```
 
+This is also the default, if no `body` is specified.
+
 ### Authentication and authorization
 
 For `auth` following mechanisms are supported:
 
-- Authentication via an Api Key. Type must be set to `api_key`.
-- Authentication via Basic Authentication. Type must be set to `basic_auth`.
+- Authentication via an API Key. `type` must be set to `api_key`.
+- Authentication via Basic Authentication. `type` must be set to `basic_auth`.
 
 For `api_key` the config looks as follows:
 
 ```yaml
-name: Some-Name
-value: The-Value-of-My-Key
-in: header # alternatively cookie
+courier:
+  delivery_strategy: http
+  http:
+    request_config:
+      # ... other config
+      auth:
+        type: api_key
+        config:
+          name: key-name
+          value: key-value
+          in: header # or cookie
 ```
 
 All properties are mandatory.
 
 For `basic_auth` the config looks as follows:
 
 ```yaml
-user: My-User
-password: My-Pass-Value
+courier:
+  delivery_strategy: http
+  http:
+    request_config:
+      # ... other config
+      auth:
+        type: basic_auth
+        config:
+          user: My-User
+          password: My-Pass-Value
 ```
 
 All properties are mandatory.

src/sidebar.js

@@ -439,6 +439,7 @@ module.exports = {
             "self-hosted/kratos/configuration/oidc",
             "kratos/guides/setting-up-password-hashing-parameters",
             "kratos/guides/select-cipher-algorithm",
+            "kratos/self-hosted/email-http",
             "kratos/reference/configuration-editor",
           ],
         },
@@ -449,7 +450,6 @@ module.exports = {
             "kratos/guides/production",
             "kratos/guides/multi-tenancy-multitenant",
             "self-hosted/operations/scalability",
-            "kratos/self-hosted/email-http",
             "kratos/self-hosted/mail-courier-templates",
             "kratos/guides/tracing",
             "kratos/guides/zero-trust-iap-proxy-identity-access-proxy",