Using the API

All Conduit features are accessible through a versioned JSON REST API at /api/v1. This reference covers authentication, common conventions, and a summary of every available endpoint. For features that are also available in the web UI, the relevant UI path is noted alongside the API endpoint.

Base URL

https://conduit.email/api/v1

Authentication

Conduit supports two distinct authentication mechanisms for API access. Both are presented identically in requests — include a token in the Authorization header:

Authorization: Bearer <token>

The server tries JWT validation first, then falls back to API token validation, so the calling code never needs to know which type of token it holds.

Method 1 — Session tokens (JWT)

Session tokens are short-lived JWTs issued when you sign in with your email and password (or via OAuth). They consist of two parts:

• Access token — valid for 15 minutes. Include this in every API request.
• Refresh token — long-lived. Exchange it for a new access token when the current one expires, without re-entering credentials.

Obtaining tokens

POST /api/v1/sessions
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "correct-horse-battery-staple"
}

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900
}

Refreshing an access token

POST /api/v1/sessions/refresh
Content-Type: application/json

{
  "refresh_token": "eyJ..."
}

Signing out

Revoking the refresh token immediately invalidates the session:

DELETE /api/v1/sessions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "refresh_token": "eyJ..."
}

The web UI equivalent is the Sign out action available from the navigation.

When to use session tokens

Session tokens are best suited for interactive, user-facing applications:

• Web and mobile apps where a human types their credentials at login time.
• Short-lived scripts or one-off API calls where you can sign in at the start and discard the tokens when done.
• Any context where you want the authentication to be tied to the account owner's active session so that signing out everywhere immediately revokes access.

Pros and cons

Method 2 — Long-lived API tokens

API tokens are opaque, long-lived credentials you create in the API or web UI. Unlike session tokens they do not expire by default and do not need to be refreshed.

See the API Tokens section below for the full CRUD reference.

When to use API tokens

API tokens are best suited for automated, non-interactive clients:

• CI/CD pipelines that need to create or update webhooks as part of a deployment.
• Server-side scripts or cron jobs that run unattended.
• Third-party integrations where you want to issue a dedicated credential per integration that can be revoked independently.
• Any context where implementing a token-refresh loop is impractical.

Scoping and restricting tokens

API tokens support two optional restrictions that reduce blast radius if a token is leaked:

• expires_in — set a finite lifetime in seconds. Useful when you only need access for a bounded period (e.g. a one-time migration).
• allowed_ips — restrict which client IPs or CIDR ranges may use the token. Useful when your automation runs from a known IP range (e.g. a GitHub Actions runner pool or a fixed office NAT).

Pros and cons

Choosing the right method

Two-factor authentication (TOTP)

If 2FA is enabled on your account, the POST /api/v1/sessions response returns a TOTP challenge instead of tokens:

{
  "totp_required": true,
  "totp_token": "..."
}

Complete the challenge with a code from your authenticator app:

POST /api/v1/sessions/2fa
Content-Type: application/json

{
  "totp_token": "...",
  "code": "123456"
}

Errors

All errors follow the same shape:

{
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

Common HTTP status codes:

Authentication-specific error codes:

Accounts

Create an account

POST /api/v1/accounts

Account creation sends a signup confirmation email. The account cannot create a session until that email has been confirmed.

Change your password

PUT /api/v1/accounts/me/password

Update your timezone

PUT /api/v1/accounts/me/timezone

The timezone setting controls how timestamps are displayed in the web UI. All timestamps in API responses remain in UTC regardless of this setting.

Request a password reset

POST /api/v1/accounts/me/password-reset

This endpoint always returns success for both known and unknown addresses. When the account exists, Conduit sends a password-reset email containing the token used by the confirmation endpoint below.

Confirm a password reset

PUT /api/v1/accounts/me/password-reset

Delete your account

DELETE /api/v1/accounts/me

This action is irreversible. All webhooks, delivery logs, security policies, and custom domains are permanently removed.

Two-factor authentication

Set up TOTP

POST /api/v1/accounts/me/2fa/setup

Returns a secret, an otpauth_url, and a qr_code_png data URI. Scan the QR code with your authenticator app.

Enable TOTP

POST /api/v1/accounts/me/2fa/enable

Disable TOTP

DELETE /api/v1/accounts/me/2fa

Backup codes

When you enable TOTP (POST /api/v1/accounts/me/2fa/enable), the response includes 8 single-use backup codes:

{
  "backup_codes": [
    "A1B2C-D3E4F",
    "G5H6I-J7K8L",
    ...
  ]
}

Save these somewhere safe. Each code can be used once in place of a TOTP code when completing the sign-in challenge (POST /api/v1/sessions/2fa). After a backup code is used, it is consumed and cannot be reused.

Regenerate backup codes

POST /api/v1/accounts/me/2fa/backup-codes

Returns a new set of 8 single-use backup codes and invalidates all previous backup codes. Requires an active 2FA session (you must already be signed in).

Webhooks

See Webhook Payload Reference for the JSON structure delivered to your target URL, template variables, and custom headers.

Create a webhook

POST /api/v1/webhooks

Note: custom_headers, payload_template, and rate_limit are currently only configurable through the API. smtp_security_policy_id can also be set via the webhook edit form in the web UI.

The secret field is only returned at creation time.

Update a webhook

PUT /api/v1/webhooks/{id}

Accepts the same fields as create. To detach the current security policy, set clear_security_policy: true.

Simulate an email delivery

Trigger a synthetic test delivery to verify that a webhook target is reachable and behaving correctly.

POST /api/v1/webhooks/{id}/simulate

The request body is optional. When provided, these fields customise the simulated email:

The response contains the delivery outcome:

A log entry with simulated: true is written to the delivery log regardless of outcome.

Delivery logs

Pagination

The list endpoint accepts two optional query parameters:

Example — fetch the second page of 100 results:

GET /api/v1/webhooks/wh_01HX.../logs?page=2&page_size=100
Authorization: Bearer <access_token>

Log entry fields

Each log entry includes:

Simulated log entries are labelled SIM in the web UI delivery log view.

SMTP security policies

See Configuring an SMTP Security Policy for a full guide.

Domains

Domain management is currently only available through the API. See Using a Custom Domain for a full guide.

Register a domain

POST /api/v1/domains

Verify a domain

POST /api/v1/domains/{id}/verify

Performs a DNS TXT lookup to confirm the verification token is published. See Using a Custom Domain for the full verification workflow.

API Tokens

Long-lived API tokens let you authenticate without short-lived JWTs — useful for CI/CD pipelines, scripts, and integrations where refreshing tokens is impractical.

Tokens are presented exactly like JWTs: Authorization: Bearer <token>. The authentication middleware tries JWT validation first, then falls back to API token validation.

Important: The raw token value is returned once at creation time. Store it securely — it cannot be retrieved again.

List tokens

GET /api/v1/accounts/me/api-tokens

Returns an array of tokens (without the raw token value).

Create a token

POST /api/v1/accounts/me/api-tokens

Response (201):

{
  "id": "tok_01HX...",
  "name": "CI/CD Pipeline",
  "token": "aB3c...raw-token-shown-once...",
  "expires_at": "2026-01-01T00:00:00Z",
  "allowed_ips": ["192.168.1.0/24"],
  "last_used_at": null,
  "created_at": "2025-01-01T12:00:00Z"
}

Revoke a token

DELETE /api/v1/accounts/me/api-tokens/{id}

Returns 204 No Content on success.