Configuring an SMTP Security Policy

An SMTP security policy controls which email Conduit accepts for a webhook. You create a policy on its own, then attach it to one or more webhooks. Several addresses can therefore share one policy, or each address can have its own.

What a policy can enforce

Control Description
Source IP allowlist Accept a connection only from the CIDR ranges that you list.
SMTP AUTH Require a sender to authenticate with a username and a password. This needs STARTTLS.
SPF verification Do a live DNS SPF lookup. Reject mail when the sending IP address is not authorized for the envelope domain.
DKIM verification Verify the DKIM signature on the message. Reject mail with a missing or invalid signature.
Domain allowlist Limit the SPF and DKIM checks to a set of trusted sender domains.

Every control is optional, and you can combine them in any way. A policy with no active control accepts all mail, within the limits of the global gateway settings.

Step 1: Create a policy

Using the web UI

  1. Go to Policies (/app/smtp-policies) in the navigation bar.
  2. Click + New.
  3. Give the policy a name and set the controls that you want. The sections below describe each control.
  4. Click Create policy.

Using the API

POST /api/v1/smtp-policies
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "trusted-senders"
}

This request creates a policy with no restrictions. Add the fields below to turn on the controls that you want.

Source IP allowlist

Conduit rejects a connection from an IP address that no listed CIDR range covers. The rejection happens at RCPT TO, with the SMTP code 550 5.7.1.

In the web UI

In the Source IP fieldset of the policy form, enter one CIDR range per line. Leave the field blank to allow a connection from any IP address.

203.0.113.0/24
198.51.100.42/32

Using the API

Set allowed_source_ips to a comma-separated list of CIDR ranges:

{
  "allowed_source_ips": "203.0.113.0/24,198.51.100.42/32"
}

SMTP AUTH

While this control is on, a sender must authenticate with a username and a password through the AUTH command. SMTP AUTH needs STARTTLS, and Conduit rejects an unauthenticated connection over plain SMTP.

Conduit stores the credentials as bcrypt hashes. To generate a hash for a password, use a cost factor of 12:

htpasswd -bnBC 12 "" "s3cr3t-p@ssw0rd" | tr -d ':\n'

In the web UI

In the SMTP AUTH fieldset:

  1. Select Require SMTP AUTH.
  2. In the Credentials text area, enter one credential per line, in the format username:$2a$hash:
sender1:$2a$12$...
sender2:$2a$12$...

Using the API

Set require_smtp_auth to true. Set smtp_credentials to a comma-separated list of username:bcrypt_hash pairs:

{
  "require_smtp_auth": true,
  "smtp_credentials": "sender1:$2y$12$...,sender2:$2y$12$..."
}

SPF verification

Conduit does a live DNS SPF lookup against the envelope sender domain and the connecting IP address. Mail that fails the SPF check is rejected at DATA, with the SMTP code 550.

In the web UI

In the SPF fieldset:

  1. Select Require SPF pass.
  2. Optional: enter the trusted sender domains, one per line, in the Allowed SPF domains text area. Conduit then accepts SPF results for those domains only. Mail from another domain is rejected, even when SPF passes. Leave the field blank to accept SPF results from any domain.

Using the API

Set require_spf to true. Optionally, set allowed_spf_domains to a comma-separated list of domains:

{
  "require_spf": true,
  "allowed_spf_domains": "trusted-partner.com,alerts.example.com"
}

DKIM verification

Conduit verifies the DKIM signature on the message at DATA time. Mail with a missing or invalid signature is rejected with the SMTP code 550.

In the web UI

In the DKIM fieldset:

  1. Select Require DKIM pass.
  2. Optional: enter the trusted signing domains, one per line, in the Allowed DKIM domains text area. Conduit then accepts a signature from those domains only. Leave the field blank to accept a signature from any domain.

Using the API

Set require_dkim to true. Optionally, set allowed_dkim_domains to a comma-separated list of domains:

{
  "require_dkim": true,
  "allowed_dkim_domains": "trusted-partner.com"
}

Combining controls

Conduit combines the controls with AND. A message must satisfy every active requirement before Conduit accepts it.

In the web UI

Turn on as many controls as you need in the same policy form. For example, a sender must connect from an approved IP range, pass SPF, and sign the message with DKIM. To require all three, select Require SPF pass and Require DKIM pass, enter the allowed domains, and complete the Source IP field. One submission of the form sets all of them.

Using the API

{
  "name": "high-security",
  "allowed_source_ips": "203.0.113.0/24",
  "require_spf": true,
  "require_dkim": true,
  "allowed_spf_domains": "partner.example.com",
  "allowed_dkim_domains": "partner.example.com"
}

Step 2: Attach the policy to a webhook

Using the web UI

  1. Go to Webhooks (/app/webhooks) and open the webhook to protect.
  2. Click Edit.
  3. In the Security policy list, select the policy that you created.
  4. Click Save.

Several webhooks can share one policy. A change to the policy takes effect immediately for every attached webhook.

Using the API

Set smtp_security_policy_id when you create or update a webhook:

PUT /api/v1/webhooks/wh_01HX...
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "smtp_security_policy_id": "pol_01HX..."
}

Detaching a policy

Using the web UI

  1. Open the Edit form of the webhook (/app/webhooks/{id}/edit).
  2. Set the Security policy list to None.
  3. Click Save.

Using the API

Set clear_security_policy to true in the update request:

PUT /api/v1/webhooks/wh_01HX...
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "clear_security_policy": true
}

Managing policies

Using the web UI

The Policies page (/app/smtp-policies) lists all of your policies, with an indicator for SPF, DKIM and SMTP AUTH. Click a policy name to open its details. Then use the Edit or Delete button.

Using the API

List all policies

GET /api/v1/smtp-policies
Authorization: Bearer <access_token>

Get one policy

GET /api/v1/smtp-policies/pol_01HX...
Authorization: Bearer <access_token>

Update a policy

PUT /api/v1/smtp-policies/pol_01HX...
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "high-security",
  "require_spf": true,
  "require_dkim": true
}

Delete a policy

CAUTION: A policy deletion detaches the policy from every webhook that uses it. Those webhooks then accept all mail again.

DELETE /api/v1/smtp-policies/pol_01HX...
Authorization: Bearer <access_token>