Using a Custom Domain

By default, webhook addresses use the public domain provided by Conduit (default: incoming.conduit.email). When using the public domain, the local part (the portion before @) is derived automatically from the webhook ID and cannot be customised — for example:

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

If you want memorable addresses on a domain you control — such as notifications@mail.yourcompany.com — you must first claim and verify that domain.

Domain verification proves to Conduit that you control the DNS for the domain, so that no other account can register webhook addresses on it.

How it works

1. You register the domain with Conduit via the API.
2. Conduit issues a unique verification token.
3. You publish the token as a DNS TXT record under the domain.
4. You ask Conduit to verify the domain.
5. Conduit performs a DNS TXT lookup and confirms the token is present.
6. Once verified, any webhook address using that domain is restricted to your account.

Step 1 — Claim the domain

Using the web UI

1. Go to Domains at /app/settings/domains.
2. Enter your domain or subdomain (for example mail.yourcompany.com).
3. Click Claim domain.
4. Copy the DNS TXT Name and Value shown in the claimed domains table.

Using the API

POST /api/v1/domains
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "mail.yourcompany.com"
}

The response includes your verification token:

{
  "id": "dom_01HX...",
  "name": "mail.yourcompany.com",
  "account_id": "acc_01HX...",
  "is_public": false,
  "verified": false,
  "verification_token": "conduit-verify-a1b2c3d4e5f6",
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Step 2 — Publish the DNS TXT record

Add a TXT record to your DNS zone for the domain. The record name and value depend on your DNS provider's interface, but the content must be exactly the verification_token value returned above.

DNS propagation typically takes a few minutes, but can take up to 48 hours depending on your provider and the TTL of existing records.

Step 3 — Verify the domain

Using the web UI

1. Return to /app/settings/domains.
2. Click Verify for the claimed domain.
3. If DNS has propagated, the status changes to Verified.

If verification fails, wait a few minutes for DNS propagation and try again.

Using the API

Once the TXT record is live, ask Conduit to verify the domain:

POST /api/v1/domains/dom_01HX.../verify
Authorization: Bearer <access_token>

Conduit performs a DNS TXT lookup for the domain. If the token is found, the domain is marked as verified and you can immediately start creating webhook addresses on it.

A successful verification response:

{
  "id": "dom_01HX...",
  "name": "mail.yourcompany.com",
  "verified": true,
  ...
}

If verification fails, Conduit returns a 422 error. Wait a few minutes for DNS propagation and try again.

Managing domains

In the web UI

• View claimed domains, status, and verification DNS instructions at /app/settings/domains.
• Use Verify to re-run verification when DNS is ready.
• Use Delete to remove a claimed private domain.

In the API

List your domains

GET /api/v1/domains
Authorization: Bearer <access_token>

Get a specific domain

GET /api/v1/domains/dom_01HX...
Authorization: Bearer <access_token>

Delete a domain

Deleting a domain does not automatically delete webhooks that use it. Those webhooks will stop receiving mail until their addresses are updated.

DELETE /api/v1/domains/dom_01HX...
Authorization: Bearer <access_token>

Using your verified domain in a webhook

Once verified, use any address on the domain when creating or updating a webhook. On a private domain you can choose any local part you like (e.g. orders@mail.yourcompany.com). This is different from the public domain, where the local part is always derived from the webhook ID.

Using the web UI

1. Go to Webhooks (/app/webhooks) and click + New (or open an existing webhook and click Edit).
2. Select Private domain from the domain selector and enter the full email address (e.g. orders@mail.yourcompany.com).
3. Fill in the target URL and save.

Using the API

POST /api/v1/webhooks
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "address": "orders@mail.yourcompany.com",
  "target_url": "https://myapp.example.com/hooks/orders"
}

Troubleshooting