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

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

Set allowed_source_ips to a comma-separated list of CIDR ranges. Connections from IPs that are not covered by any listed range are rejected at RCPT TO with SMTP code 550 5.7.1.

{
  "name": "office-only",
  "allowed_source_ips": "203.0.113.0/24,198.51.100.42/32"
}

SMTP AUTH

Set require_smtp_auth to true and provide smtp_credentials as a comma-separated list of username:bcrypt_hash pairs. SMTP AUTH requires STARTTLS; unauthenticated connections over plain SMTP are rejected.

Generate a bcrypt hash for a password (cost factor 12 recommended):

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

Supply the credentials in the policy:

{
  "name": "auth-required",
  "require_smtp_auth": true,
  "smtp_credentials": "sender1:$2y$12$...,sender2:$2y$12$..."
}

Senders must present valid credentials with the AUTH command during the SMTP session.

SPF verification

Set require_spf to true. 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.

Optionally, set allowed_spf_domains to a comma-separated list of domains. When set, Conduit accepts SPF results only for those domains; mail from other domains is rejected even if SPF passes.

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

DKIM verification

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

Optionally, set allowed_dkim_domains to a comma-separated list of domains. Only signatures from those domains are accepted.

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

Combining controls

Controls are ANDed: a message must satisfy every enabled requirement to be accepted. The following policy requires that the sender connects from an approved IP range, passes SPF, and signs the message with DKIM:

{
  "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>