Getting Started with Conduit

Conduit is a hosted service that bridges inbound email to HTTP webhooks. When an email arrives at your Conduit address, Conduit immediately delivers it as an HTTP POST to a URL you configure. This guide walks you through creating an account and setting up your first webhook.

1. Create an account

Using the web UI

  1. Go to conduit.email/app/signup.
  2. Enter your email address and choose a password of at least 12 characters.
  3. Click Create account.

Conduit sends a branded confirmation email with a direct verification link (and a plain-text fallback). Open the link in that email before signing in for the first time.

Sign up with Google or GitHub

You can also click Sign up with Google or Sign up with GitHub instead. This creates an account automatically using your provider-verified email address. No password or email confirmation is required.

2. Sign in

Using the web UI

Go to conduit.email/app/signin, enter your email and password, and click Sign in.

Sign in with Google or GitHub

You can also click Sign in with Google or Sign in with GitHub to sign in without a password. If your email address matches an existing account, the OAuth provider is linked to that account; your password is not needed and is not affected.

If two-factor authentication is enabled on your account you are prompted for a code from your authenticator app before being taken to the dashboard.

If your email address is still unconfirmed, the sign-in page also includes a form to request another confirmation link.

3. Set up two-factor authentication

Enabling two-factor authentication (2FA) adds a second layer of security to your account. After you sign in with your password, you are prompted for a time-based one-time code from your authenticator app.

  1. Open the user menu (bottom-left on desktop, bottom navigation on mobile), go to Two-factor auth (/app/settings/account/2fa), and click Set up two-factor authentication.
  2. Scan the QR code with an authenticator app (e.g. Google Authenticator, Authy, 1Password).
  3. Enter the 6-digit code from your app to confirm the setup.
  4. Save your backup codes. Conduit generates 8 single-use backup codes that let you sign in if you lose access to your authenticator device. Store them somewhere safe.

From that point on, every sign-in will require both your password and a code from your authenticator app.

3b. Register a passkey (optional)

Passkeys let you sign in with biometrics (Touch ID, Face ID) or a hardware security key — no password required. They are phishing-resistant and work alongside your existing password and 2FA setup.

Note: Passkeys are only available when the server has been configured with an app_base_url. Ask your administrator if the Passkeys item does not appear in your user menu (bottom-left on desktop, bottom navigation on mobile).

  1. Open the user menu and go to Passkeys (/app/settings/passkeys).
  2. Click Register passkey.
  3. Give the passkey a recognisable name (e.g. "MacBook Touch ID" or "YubiKey 5").
  4. Follow the browser prompt to authenticate with your device.

To sign in with a passkey, click Sign in with passkey on the sign-in page and follow your device's prompt. Passkeys saved in password managers (for example Bitwarden) are supported.

4. Create your first webhook

A webhook maps an email address to an HTTP endpoint. When an email arrives at the address, Conduit posts the message to your endpoint.

Public domain vs. custom domain

Conduit has one public domain (incoming.conduit.email). Every account can create webhooks on it; no verification required. When you use the public domain, the local part (the part before @) is derived automatically from the webhook ID and cannot be changed:

webhook-01HX...@incoming.conduit.email

If you need a memorable address like orders@mail.yourcompany.com, you must first claim and verify your own domain. See Using a Custom Domain for details.

Using the web UI

  1. Go to Webhooks (/app/webhooks) and click + New.
  2. To use the public domain, leave the domain selector set to Public; the address is assigned automatically after you save. To use one of your verified private domains, select Private domain and enter the full email address (e.g. alerts@mail.yourcompany.com).
  3. Enter the target HTTPS URL that should receive the webhook payload.
  4. Click Create webhook.

The webhook detail page shows the generated secret. Copy this secret now; it is not shown again. You need it to verify the signature on your endpoint.

5. Verify the signature on your endpoint

Every delivery from Conduit includes an X-Conduit-Signature header containing an HMAC-SHA256 signature of the raw request body, keyed with your webhook secret:

X-Conduit-Signature: sha256=<hex-encoded-digest>

Verify this signature in your endpoint before processing the payload:

import hmac
import hashlib

def verify_signature(body: bytes, secret: str, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Reject requests where the signature does not match.

If you need to rotate the secret, use the Rotate secret button on the webhook detail page in the UI.

6. Test your webhook

Using the web UI

The quickest way to verify your endpoint is reachable is the Simulate action. It skips SMTP entirely and asks Conduit to POST a synthetic payload directly to your target URL.

  1. Open the webhook detail page (/app/webhooks/{id}).
  2. Click Simulate and confirm.
  3. Conduit posts a test payload immediately and records the result in Recent Deliveries.

See Testing Webhooks for details on the Simulate feature, including how to customise the synthetic sender, subject, and body via the API.

Sending a real email over SMTP

To exercise the full inbound path — including any attached SMTP security policy and DNS routing — send a real email through the Conduit SMTP gateway.

The gateway listens at mx.conduit.email on port 25 with STARTTLS support. Point any mail client or sending system at that host and address your email to the webhook address.

Quick SMTP test with swaks

swaks is a command-line SMTP testing tool available on most platforms (brew install swaks, apt install swaks):

swaks \
  --to webhook-01HX...@incoming.conduit.email \
  --from you@example.com \
  --server mx.conduit.email \
  --port 25 \
  --body "Hello from swaks"

SMTP response codes

Conduit returns an SMTP status code that reflects the delivery outcome:

Outcome SMTP code Meaning
Success (HTTP 2xx) 250 Message accepted
Transient failure (HTTP 5xx / timeout) 450 MTA will retry
Permanent failure (HTTP 4xx) 550 MTA will bounce

To review delivery attempts, open the webhook detail page in the UI and click Logs.

Password resets

Request a password reset from conduit.email/app/reset-password in the web UI. Conduit sends a reset email with a single-use link to choose a new password. After a successful reset confirmation, Conduit revokes all refresh tokens and API access tokens for the account.

Next steps

Checklist

Use this checklist to track your progress through the setup steps:

  • Created an account and confirmed your email address
  • Signed in for the first time
  • Set up two-factor authentication (2FA)
  • Created your first webhook
  • Verified the webhook signature on your endpoint
  • Tested delivery (via Simulate or a test email) and confirmed the result