Getting Started with Conduit

Conduit is a hosted service that connects inbound email to HTTP webhooks. When an email arrives at your Conduit address, Conduit delivers it immediately as an HTTP POST to a URL that you configure. This guide covers how to create an account and how to set 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 confirmation email with a verification link and a plain-text fallback. Open that link before you sign in for the first time.

Sign up with Google or GitHub

You can also click Sign up with Google or Sign up with GitHub. Conduit then creates the account from the verified email address of your provider. No password and no email confirmation are necessary.

2. Sign in

Using the web UI

Go to conduit.email/app/signin, enter your email address 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, Conduit links the OAuth provider to that account. Your password stays as it is and is not necessary for this method.

If two-factor authentication is on, Conduit asks for a code from your authenticator app before it opens the dashboard.

If your email address is still unconfirmed, the sign-in page also shows a form that requests another confirmation link.

3. Set up two-factor authentication

Two-factor authentication (2FA) adds a second layer of security to your account. After you sign in with your password, Conduit asks 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, for example Google Authenticator, Authy or 1Password.
  3. Enter the 6-digit code from your app to complete the setup.
  4. Save your backup codes. Conduit generates 8 single-use backup codes. They let you sign in if you lose access to your authenticator device. Store them in a safe place.

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

3b. Register a passkey (optional)

A passkey signs you in with biometrics (Touch ID, Face ID) or with a hardware security key. No password is necessary. Passkeys resist phishing and work together with your existing password and 2FA.

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

  1. Open the user menu and go to Passkeys (/app/settings/passkeys).
  2. Click Register passkey.
  3. Give the passkey a name that you recognize, for example "MacBook Touch ID" or "YubiKey 5".
  4. Obey the browser prompt to authenticate with your device.

To sign in with a passkey, click Sign in with passkey on the sign-in page, then obey the prompt from your device. Conduit supports passkeys that are saved in a password manager, for example Bitwarden.

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 compared to custom domain

Conduit has one public domain (incoming.conduit.email). Every account can create webhooks on it, and no verification is necessary. On the public domain the local part (the part before @) comes from the webhook ID. You cannot change it:

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

For a memorable address such as orders@mail.yourcompany.com, first claim and verify your own domain. For the details, see Using a Custom Domain.

Using the web UI

  1. Go to Webhooks (/app/webhooks) and click + New.
  2. To use the public domain, leave the domain selector on Public. Conduit assigns the address after you save. To use one of your verified private domains, select Private domain and enter the full email address, for example alerts@mail.yourcompany.com.
  3. Enter the target HTTPS URL that receives the webhook payload.
  4. Click Create webhook.

The webhook detail page shows the generated secret. Copy this secret now. Conduit does not show it again. You need it to verify the signature on your endpoint.

5. Verify the signature on your endpoint

Every delivery from Conduit carries an X-Conduit-Signature header. The header holds 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 you process 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 a request when the signature does not match.

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 Simulate action is the quickest way to test that your endpoint is reachable. It skips SMTP 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.

Testing Webhooks covers the Simulate feature in detail, including how to set your own synthetic sender, subject and body through the API.

Sending a real email over SMTP

A real email through the Conduit SMTP gateway exercises the full inbound path. That path includes any attached SMTP security policy and the DNS routing.

The gateway listens at mx.conduit.email on port 25 and supports STARTTLS. 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 test tool for 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 for the delivery outcome:

Outcome SMTP code Meaning
Success (HTTP 2xx) 250 Message accepted
Transient failure (HTTP 5xx / timeout) 450 The MTA retries
Permanent failure (HTTP 4xx) 550 The MTA bounces the message

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

Password resets

Request a password reset at 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, Conduit revokes all refresh tokens and all 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 (with Simulate or a test email) and read the result