# Set up inbound email

> Publish the inbound MX record for your verified domain, choose the inbound subdomain, verify the record and send a test message.

This guide connects a subdomain of your domain to Emailit so it can receive email. It takes one DNS record and doesn't change how mail to your main domain is delivered.

## Before you begin

- A [verified sending domain](/docs/domains/verification/) in your workspace, for example `acme.com`. Inbound only works on verified domains. If you haven't added one yet, follow [Add a domain](/docs/domains/add-a-domain/).
- Access to the DNS settings for that domain.
- Available credits. Each received message costs 1 credit.
- Domains are created with incoming mail enabled (the `incoming` field is `true` by default). Leave it that way; there's no dashboard switch for it.

## Choose the inbound subdomain

Emailit accepts mail for one subdomain per domain. By default it's `inbound`, so the addresses look like `anything@inbound.acme.com`. You can see the current value on the domain page under **Custom Subdomains** > **Inbound Subdomain**. The field is read-only in the dashboard.

To use a different subdomain, set `inbound_key` with [Update a domain](/docs/api-reference/domains/update/). The value can contain lowercase letters, digits and hyphens, can be 1 to 63 characters long, and can't start or end with a hyphen.

```bash
curl -X POST https://api.emailit.com/v2/domains/dom_2xGk5Pz8QwR1mT4vLsB7nY3cK9a \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_key": "mail"}'
```

With `"inbound_key": "mail"`, the addresses become `anything@mail.acme.com` and the MX record moves to `mail.acme.com`. Changing the key resets the inbound record's status to pending, and mail sent to the old subdomain is no longer accepted. Set `inbound_key` to `null` to go back to `inbound`.

## Add the MX record

1. **Open the domain.** In the dashboard, go to **Email API → Domains**, select your domain and open the **DNS Setup** tab.

2. **Find the inbound record.** It's the optional MX record whose name is `inbound` (or your custom subdomain) and whose value is `inbound.emailitmail.com`. Use the copy buttons to avoid typos.

3. **Create the record at your DNS provider.** Add a new record with these values:

   | Field | Value |
   | --- | --- |
   | Type | `MX` |
   | Name / Host | `inbound` (some providers want the full name, `inbound.acme.com`) |
   | Mail server / Value | `inbound.emailitmail.com` |
   | Priority | `10` |
   | TTL | Auto, or your provider's default |

   Don't change the MX records on the root domain (`acme.com`). They keep routing your normal mail to your mailbox provider.

   If your domain uses [Cloudflare one-click setup](/docs/domains/cloudflare/), you can select the **Inbound** record in the setup dialog instead of adding it by hand.

4. **Check DNS.** Back on the domain page, select **Check DNS**. The inbound record shows **OK** when an MX record with priority 10 points to `inbound.emailitmail.com`. Most providers publish records within minutes, but it can take up to 48 hours.

   You can also check from a terminal:

```bash
dig MX inbound.acme.com +short
# 10 inbound.emailitmail.com.
```

## Send a test message

From any personal mailbox, send an email to an address on the subdomain, for example `test@inbound.acme.com`.

## Verify it worked

- **Dashboard:** go to **Email API → Emails** and open the **Incoming** tab. The message appears with status **Received** within seconds. Open it to see its headers, content and attachments.
- **Events:** **Email API → Events** shows an `email.received` event. Its payload contains the email ID.
- **API:** list inbound messages with [List emails](/docs/api-reference/emails/list/):

```bash
curl "https://api.emailit.com/v2/emails?type=inbound" \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

Next, [process received mail with a webhook](/docs/inbound/process-with-webhooks/) or [forward it with an automation](/docs/inbound/forward-with-automations/).

## Troubleshooting

<details>
<summary>The record shows Missing or Invalid</summary>

The status message tells you what Emailit found. "There are no MX records at inbound.acme.com" means the record isn't published yet, or it was created on the wrong name (for example `inbound.acme.com.acme.com` when the provider appends the domain automatically). An "Invalid" status lists the records found and the expected `10 inbound.emailitmail.com`. Fix the priority or value, wait for DNS to update, then select **Check DNS** again.

</details>

<details>
<summary>I pointed my root domain's MX at Emailit</summary>

Emailit only accepts mail for the inbound subdomain. If the MX records for `acme.com` point to `inbound.emailitmail.com`, mail to `you@acme.com` is rejected with `530 Authentication required`. Restore the root MX records your mailbox provider gave you, and add the MX record on `inbound.acme.com` only.

</details>

<details>
<summary>The record shows OK, but mail goes somewhere else</summary>

Another MX record on the same name can take precedence. Mail servers use the record with the lowest priority number first, so an extra record such as `5 mx.example.net` on `inbound.acme.com` wins over Emailit's `10`. A wildcard MX record (`*.acme.com`) can also catch the subdomain if the inbound record is missing. Run `dig MX inbound.acme.com +short` and make sure `inbound.emailitmail.com` is the only answer. A CNAME on the same name also blocks MX records; remove it.

</details>

<details>
<summary>Senders get "530 Authentication required"</summary>

Emailit didn't recognize the recipient domain. Check that the address uses the current inbound subdomain (after changing `inbound_key`, the old subdomain stops working), that the domain is spelled correctly, and that the domain is still verified in **Email API → Domains**.

</details>

<details>
<summary>Senders get "452 Insufficient credits to receive inbound email"</summary>

The workspace is out of credits. `452` is a temporary error, so most sending servers keep retrying for hours or days. [Buy credits](/docs/billing/credits/) or turn on [auto-refill](/docs/billing/auto-refill/), and the retried messages are accepted.

</details>

<details>
<summary>Senders get "535 Mail server has been suspended" or "552 Message too large"</summary>

`535` means the workspace is suspended; see [Sending health](/docs/deliverability/sending-health/) or contact support. `552` means the message is larger than 40 MB.

</details>

## Related

  - [Process with webhooks](/docs/inbound/process-with-webhooks/)
  - [DNS records](/docs/domains/dns-records/)

---
Source: https://emailit.com/docs/inbound/set-up/