Configuring an SMTP Security Policy

An SMTP security policy lets you control exactly which email Conduit will accept for a webhook. Policies are created independently and then attached to one or more webhooks, so you can share a single policy across multiple addresses or assign different policies to each.

What a policy can enforce

Control Description
Source IP allowlist Accept connections only from specified CIDR ranges.
SMTP AUTH Require senders to authenticate with a username and password (requires STARTTLS).
SPF verification Perform a live DNS SPF lookup and reject mail whose sending IP is not authorised for the envelope domain.
DKIM verification Verify the DKIM signature on the message and reject mail with missing or invalid signatures.
Domain allowlist Restrict SPF/DKIM checks to a specific set of trusted sender domains.

All controls are optional and can be combined in any way. A policy with no controls enabled accepts all mail (subject to any 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 configure the controls you want (see the sections below for details on each option).
  4. Click Create policy.

Using the API

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

{
  "name": "trusted-senders"
}

This creates a policy with no restrictions. Add the fields described below to enable specific controls.

Source IP allowlist

Connections from IPs that are not covered by any listed CIDR range are rejected at RCPT TO with 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 connections from any IP.

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

When enabled, senders must authenticate with a username and password using the AUTH command. SMTP AUTH requires STARTTLS; unauthenticated connections over plain SMTP are rejected.

Credentials are stored as bcrypt hashes. Generate a hash for a password (cost factor 12 recommended):

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

In the web UI

In the SMTP AUTH fieldset:

  1. Check Require SMTP AUTH.
  2. In the Credentials textarea, 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 and 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 performs a live DNS SPF lookup against the envelope sender domain and the connecting IP. Mail that fails the SPF check is rejected at DATA with SMTP code 550.

In the web UI

In the SPF fieldset:

  1. Check Require SPF pass.
  2. Optionally, enter trusted sender domains (one per line) in the Allowed SPF domains textarea. When set, Conduit accepts SPF results only for those domains; mail from other domains is rejected even if SPF passes. Leave 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 SMTP code 550.

In the web UI

In the DKIM fieldset:

  1. Check Require DKIM pass.
  2. Optionally, enter trusted signing domains (one per line) in the Allowed DKIM domains textarea. Only signatures from those domains are accepted. Leave blank to accept signatures 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

Controls are ANDed: a message must satisfy every enabled requirement to be accepted.

In the web UI

Enable as many controls as you need within the same policy form. For example, to require that the sender connects from an approved IP range, passes SPF, and signs the message with DKIM, check Require SPF pass and Require DKIM pass, enter the allowed domains, and fill in the Source IP field, all in a single form submission.

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 you want to protect.
  2. Click Edit.
  3. In the Security policy dropdown, select the policy you created.
  4. Click Save.

Multiple webhooks can share the same policy. Changes to the policy take effect immediately for all attached webhooks.

Using the API

Set smtp_security_policy_id when creating or updating 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 webhook's Edit form (/app/webhooks/{id}/edit).
  2. Set the Security policy dropdown 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 your policies with SPF, DKIM, and SMTP AUTH indicators at a glance. Click a policy name to view its details, then use the Edit or Delete buttons to manage it.

Using the API

List all policies

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

Get a specific 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

Deleting a policy detaches it from all webhooks that reference it. Those webhooks revert to accepting all mail.

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