Using a Custom Domain

By default, a webhook address uses the public domain from Conduit (incoming.conduit.email). On the public domain the local part (the part before @) comes from the webhook ID, and you cannot change it. For example:

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

For memorable addresses on a domain that you control, such as notifications@mail.yourcompany.com, first claim and verify that domain.

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

How it works

You register the domain with Conduit.
Conduit issues a unique verification token.
You publish the token as a DNS TXT record under the domain.
You add an MX record that points to mx.conduit.email, so that incoming mail goes to Conduit.
You ask Conduit to verify the domain.
Conduit does a DNS TXT lookup for the token, and a DNS MX lookup to make sure that the record points to mx.conduit.email.
After the verification, every webhook address on that domain belongs to your account only.

Step 1: Claim the domain

Using the web UI

Go to Domains at /app/settings/domains.
Enter your domain or subdomain, for example mail.yourcompany.com.
Click Claim domain.
Copy the DNS TXT Name and Value from the table of claimed domains.

Using the API

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

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

The response carries 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: Add DNS records

You need two DNS records. The MX record routes mail to Conduit. The TXT record proves that you own the domain.

MX record (routes incoming mail to Conduit)

Field	Value
Type	`MX`
Name / Host	`mail.yourcompany.com`
Priority	`10`
Value	`mx.conduit.email`
TTL	Any value (300 seconds is a good choice)

Without this record, a sending mail server cannot find Conduit when somebody emails an address on your domain.

TXT record (proves that you own the domain)

Add a TXT record to the DNS zone of the domain. The record name and the value depend on the interface of your DNS provider. The content must be exactly the verification_token value from the response above.

Field	Value
Type	`TXT`
Name / Host	`_conduit-verify.mail.yourcompany.com`
Value	`conduit-verify-a1b2c3d4e5f6`
TTL	Any value (60 seconds or more is a good choice)

DNS propagation usually takes a few minutes. It can take up to 48 hours, and the time depends on your provider and on the TTL of the existing records.

Step 3: Verify the domain

Using the web UI

Go back to /app/settings/domains.
Click Verify for the claimed domain.
After DNS propagation, the status changes to Verified.

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

Using the API

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

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

Conduit does a DNS TXT lookup for the domain, and a DNS MX lookup to make sure that the MX record points to mx.conduit.email. If both lookups pass, Conduit marks the domain as verified. You can then create webhook addresses on it immediately.

A successful verification response:

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

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

Managing domains

In the web UI

Read the claimed domains, their status, and the verification DNS instructions at /app/settings/domains.
Use Verify to run the verification again 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 one domain

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

Delete a domain

CAUTION: A domain deletion does not delete the webhooks that use the domain. Those webhooks stop receiving mail until you update their addresses.

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

Using your verified domain in a webhook

After the verification, use any address on the domain when you create or update a webhook. On a private domain you choose the local part, for example orders@mail.yourcompany.com. The public domain is different, because there the local part always comes from the webhook ID.

Using the web UI

Go to Webhooks (/app/webhooks) and click + New. Or open an existing webhook and click Edit.
Select Private domain in the domain selector, then enter the full email address, for example orders@mail.yourcompany.com.
Enter 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

Problem	Probable cause	What to do
Verification returns 422	The TXT record or the MX record did not propagate yet	Wait, then try again. To examine the records, run `dig TXT _conduit-verify.mail.yourcompany.com` and `dig MX mail.yourcompany.com`.
Mail does not arrive	The MX record is absent, or it points somewhere else	Run `dig MX mail.yourcompany.com`. It must return `mx.conduit.email`.
You cannot create a webhook address	The domain is unverified, or it belongs to another account	Verify the domain first. Or omit the `address` field to use the public domain.
The TXT lookup succeeds but the token does not match	The published token value is wrong	Read the `verification_token` field on the domain and publish it again.
An `address_lhs_not_allowed` error	You set your own address on the public domain	Omit the `address` field to use the public domain, or enter an address on a verified private domain.