Skip to main content

Setting it up

In Settings → Installation → Incoming email:

FieldWhat
Email serviceNone, Cloudflare Email Routing, Resend, Mailgun or Postmark.
SecretWhat the service proves itself with: Resend's signing secret, Mailgun's signing key, or one you choose for Cloudflare and Postmark (Generate a secret makes one). Never shown again after saving.
Reply domainThe domain of the reply addresses, like reply.example.com.

Below them the section shows the webhook address to give the service, short setup steps for the service you chose, the reply domain each brand uses, and the last email received with what happened to it.

[!TIP] Use a subdomain of its own, like reply.example.com. The service's MX records go on that subdomain only, so they never clash with the company's normal email on example.com.

A brand can have its own reply domain (Settings → Brands → Reply domain), for example reply.example.org for a brand on another domain; brands without one use the installation's. Every reply domain must be set up with the same service.

Testing the setup​

Send a test reply runs a generated reply from you through the whole handler, to a case of its own (Test of incoming email, in the first organization, with you as the requester), and shows what happened. The same case is used next time. It checks the desk's side: the address, matching and quote removal. To check the service and DNS, answer a real case email.

Cloudflare Email Routing​

Free, and a good fit when the domain is on Cloudflare already. Email Routing hands each email to a small Email Worker that ships with the desk (integrations/cloudflare-email-worker/), and the Worker posts it to the desk signed with the secret.

  1. In the desk choose Cloudflare, Generate a secret, enter the reply domain, and save.
  2. In Cloudflare, on the domain: Email → Email Routing, and enable it for the subdomain reply.example.com. Cloudflare adds the MX and SPF records for it.
  3. Deploy the Worker, with DESK_URL set to the desk's public address and the secret DESK_SECRET set to the desk's secret. The Worker's README has the commands, and how to paste it into the dashboard instead.
  4. Email Routing → Routing rules → Catch-all address on the subdomain: Send to a Worker, that Worker.

Resend​

  1. In Resend, add reply.example.com as a domain with receiving turned on, and add the MX record Resend shows at your DNS host.
  2. Webhooks → Add endpoint: the webhook address from the desk, event email.received.
  3. Copy the endpoint's signing secret (whsec_…) into Secret in the desk and choose Resend.

Resend's webhook only says that an email came in; the desk fetches the email with the Resend API key under Email (the same key that sends).

[!WARNING] The key needs Full access: a key with sending access only can't read received emails.

Mailgun​

  1. In Mailgun, add reply.example.com as a domain and its MX records (mxa.mailgun.org and mxb.mailgun.org) at your DNS host.
  2. Receiving → Create route: expression type Match recipient, .*@reply.example.com, action Forward to the webhook address from the desk. It ends in /mime: only then does Mailgun send the original email.
  3. Copy the HTTP webhook signing key (Settings → API security) into Secret and choose Mailgun.

Postmark​

  1. In Postmark's inbound stream, set the inbound domain to reply.example.com and point its MX record to inbound.postmarkapp.com.
  2. Set the inbound webhook to the desk's address with the secret as the password: https://desk:<secret>@support.example.com/api/v1/inbound/postmark.
  3. Turn on Include raw email content in JSON payload. Without it the desk refuses the emails.