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://<your-conduit-host>/api/v1

Authentication

Most endpoints require a Bearer token. Obtain one by signing in (see Getting Started).

Include the token in the Authorization header:

Authorization: Bearer <access_token>

Refreshing a token

Access tokens expire after 15 minutes. Refresh without re-entering credentials:

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

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

Signing out

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.

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:

Status	Meaning
`400`	Bad request — malformed JSON or missing required fields
`401`	Unauthorized — missing or invalid access token
`404`	Not found
`409`	Conflict — e.g. email address already registered
`422`	Validation error — request was understood but values are invalid

Accounts

Operation	API	Web UI
Create account	`POST /api/v1/accounts`	`/app/signup`
Get your account	`GET /api/v1/accounts/me`	—
Change password	`PUT /api/v1/accounts/me/password`	`/app/settings/account`
Update timezone	`PUT /api/v1/accounts/me/timezone`	`/app/settings/account`
Request password reset	`POST /api/v1/accounts/password-reset`	`/app/reset-password`
Confirm password reset	`PUT /api/v1/accounts/password-reset`	`/app/reset-password/confirm`
Delete account	`DELETE /api/v1/accounts/me`	—

Create an account

POST /api/v1/accounts

Field	Type	Required	Description
`email`	string	Yes	Account email address
`password`	string	Yes	Minimum 12 characters

Change your password

PUT /api/v1/accounts/me/password

Field	Type	Required	Description
`current_password`	string	Yes	Your current password
`new_password`	string	Yes	Minimum 12 characters

Update your timezone

PUT /api/v1/accounts/me/timezone

Field	Type	Required	Description
`timezone`	string	Yes	IANA timezone name (e.g. `America/New_York`, `Europe/Berlin`, `UTC`)

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/password-reset

Field	Type	Required	Description
`email`	string	Yes	Account email address

Confirm a password reset

PUT /api/v1/accounts/password-reset

Field	Type	Required	Description
`token`	string	Yes	Reset token (from the reset email)
`new_password`	string	Yes	Minimum 12 characters

Delete your account

DELETE /api/v1/accounts/me

Field	Type	Required	Description
`password`	string	Yes	Current password to confirm deletion

Two-factor authentication

Operation	API	Web UI
Set up TOTP	`POST /api/v1/accounts/me/2fa/setup`	`/app/settings/2fa/setup`
Enable TOTP	`POST /api/v1/accounts/me/2fa/enable`	`/app/settings/2fa/setup` (same form)
Disable TOTP	`DELETE /api/v1/accounts/me/2fa`	`/app/settings/account`
Regenerate backup codes	`POST /api/v1/accounts/me/2fa/backup-codes`	`/app/settings/account`

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

Field	Type	Required	Description
`code`	string	Yes	6-digit code from your authenticator app

Disable TOTP

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

Field	Type	Required	Description
`code`	string	Yes	6-digit TOTP code to confirm

Regenerate backup codes

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

Returns a new set of single-use backup codes.

Webhooks

Operation	API	Web UI
List webhooks	`GET /api/v1/webhooks`	`/app/webhooks`
Create a webhook	`POST /api/v1/webhooks`	`/app/webhooks/new`
Get a webhook	`GET /api/v1/webhooks/{id}`	`/app/webhooks/{id}`
Update a webhook	`PUT /api/v1/webhooks/{id}`	`/app/webhooks/{id}/edit`
Delete a webhook	`DELETE /api/v1/webhooks/{id}`	`/app/webhooks/{id}` (Delete button)
Toggle active state	—	`/app/webhooks/{id}` (Activate/Deactivate button)
Rotate secret	—	`/app/webhooks/{id}` (Rotate secret button)
View delivery logs	`GET /api/v1/webhooks/{id}/logs`	`/app/webhooks/{id}/logs`

Create a webhook

POST /api/v1/webhooks

Field	Type	Required	Description
`address`	string	No	Full email address to receive mail (e.g. `alerts@mail.example.com`). Omit to use the public domain; the local part is derived automatically from the webhook ID and cannot be customised. Providing an address on the public domain is rejected (`address_lhs_not_allowed`).
`target_url`	string	Yes	HTTPS URL to deliver the webhook payload to
`secret`	string	No	Custom HMAC secret; auto-generated if omitted
`active`	boolean	No	Defaults to `true`
`custom_headers`	object	No	Key/value headers to include in every delivery
`payload_template`	string	No	Go `text/template` for the JSON payload
`rate_limit`	integer	No	Max emails per minute (`0` = disabled)
`smtp_security_policy_id`	string	No	ID of an SMTP security policy to attach

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.

Delivery logs

Operation	API	Web UI
List logs for a webhook	`GET /api/v1/webhooks/{id}/logs`	`/app/webhooks/{id}/logs`
Get a specific log entry	`GET /api/v1/webhooks/{id}/logs/{logId}`	—

Each log entry includes:

Field	Description
`id`	Log entry ID
`webhook_id`	Webhook ID
`smtp_message_id`	SMTP `Message-ID` header value
`sender`	Envelope sender address
`http_status`	HTTP status code returned by the target (if reached)
`error`	Error detail, if delivery failed
`duration_ms`	Delivery round-trip time in milliseconds
`attempted_at`	Timestamp of the delivery attempt

SMTP security policies

See Configuring an SMTP Security Policy for a full guide.

Operation	API	Web UI
List policies	`GET /api/v1/smtp-policies`	`/app/smtp-policies`
Create a policy	`POST /api/v1/smtp-policies`	`/app/smtp-policies/new`
Get a policy	`GET /api/v1/smtp-policies/{id}`	`/app/smtp-policies/{id}`
Update a policy	`PUT /api/v1/smtp-policies/{id}`	`/app/smtp-policies/{id}/edit`
Delete a policy	`DELETE /api/v1/smtp-policies/{id}`	`/app/smtp-policies/{id}` (Delete button)

Domains

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

Operation	API
List domains	`GET /api/v1/domains`
Register a domain	`POST /api/v1/domains`
Get a domain	`GET /api/v1/domains/{id}`
Verify a domain	`POST /api/v1/domains/{id}/verify`
Delete a domain	`DELETE /api/v1/domains/{id}`

Register a domain

POST /api/v1/domains

Field	Type	Required	Description
`name`	string	Yes	Domain name to claim (e.g. `mail.example.com`)

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.