HTTP based email delivery

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

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

config.yml

courier:
  delivery_strategy: http
  http:
    request_config:
      url: https://api.crm.com/email
      method: POST
      body: file://.mail.api.request.jsonnet
      headers:
        "Content-Type": "application/json"
      auth:
        type: basic_auth
        config:
          user: YourUsername
          password: YourPass

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 referring to local files. This property is ignored for HTTP methods, which don't support sending of HTTP body payloads (TRACE).
• auth - configuration of authentication and authorization mechanisms to be used by request

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:

• recovery_invalid
  • To
• recovery_valid
  • To
  • RecoveryURL
  • Identity
• recovery_code_invalid
  • To
• recovery_code_valid
  • To
  • RecoveryCode
  • Identity
• verification_invalid
  • To
• verification_valid
  • To
  • VerificationURL
  • Identity
• verification_code_invalid
  • To
• verification_code_valid
  • To
  • VerificationCode
  • Identity

A universal Jsonnet template that works with all flows, would look like this:

function(ctx) {
  recipient: ctx.Recipient,
  template_type: ctx.TemplateType,
  name: if "TemplateData" in ctx && "Identity" in ctx.TemplateData && "Name" in ctx.TemplateData.Identity then ctx.TemplateData.Identity.Name else null,
  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,
}

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.

For api_key the config looks as follows:

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:

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.