> ## Documentation Index
> Fetch the complete documentation index at: https://dugble.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sender domains

> Authenticate the domains used to send email through Dugble

A sender domain is the domain used in the `From` address of your email. Authenticating that domain allows receiving mail systems to verify that Dugble is authorized to send on its behalf.

For example, sending from `notifications@example.com` requires control of `example.com` or an appropriate sending subdomain such as `mail.example.com`.

## Why domain authentication matters

Domain authentication helps you establish a consistent sender identity, reduce spoofing risk, and give receiving systems the SPF and DKIM signals they need to evaluate your mail.

It also gives you the foundation for publishing a DMARC policy for your visible From domain.

## Add a sender domain

<Steps>
  <Step title="Choose a sending domain">
    Use a domain or subdomain you control. A dedicated subdomain such as `mail.example.com` can separate transactional sending from other mail streams.
  </Step>

  <Step title="Create the domain in Dugble">
    Add the domain to your team and choose a supported sending region. Dugble currently supports `us-east-1` and `eu-north-1`. You can optionally set `tls` to `opportunistic` or `enforced`; when omitted, it defaults to `opportunistic`.
  </Step>

  <Step title="Publish the DNS records">
    Add every verification record returned by Dugble at your DNS provider. Copy host names and values exactly.
  </Step>

  <Step title="Verify the domain">
    After DNS changes propagate, run domain verification again. Do not send from the domain until its status is `verified`.
  </Step>
</Steps>

The supported sender-domain configuration is intentionally small:

```json theme={null}
{
  "name": "mail.example.com",
  "region": "eu-north-1",
  "tls": "enforced"
}
```

Tracking settings, receiving capabilities, and custom return-path settings are not customer-configurable sender-domain fields. Unknown JSON fields are rejected by the API.

## List sender domains

`GET /domains` uses `limit` and `offset` pagination and returns a plain array inside the standard success envelope.

* `limit` defaults to `50` when omitted, non-positive, or greater than `100`.
* `offset` defaults to `0`, and negative values are treated as `0`.
* Malformed integer values for `limit` or `offset` return `400 Bad Request`.

The response does not include `has_more`, so clients that need to enumerate all domains should advance `offset` by the number of records returned and stop when a page contains fewer than the requested effective limit.

## Update a sender domain

Use `PATCH /domains/{domain_id}` to change mutable sender-domain configuration. The current backend exposes domain updates through the same sender-domain create permission used for provisioning and verification.

Only fields supported by the public update request should be sent. Provider internals and persistence-only fields are not customer-configurable.

See [Choosing a Region](/docs/domains/regions) for the supported regions and TLS options.

## Provisioning

Creating a domain may complete immediately or return an asynchronous provisioning response while Dugble prepares the sending infrastructure for the selected region.

If provisioning is still in progress, wait for the suggested retry interval before checking again.

## Domain states

| State                | Meaning                                                                         |
| -------------------- | ------------------------------------------------------------------------------- |
| `not_started`        | Verification has not started yet.                                               |
| `pending`            | Verification is in progress or DNS records are still incomplete.                |
| `verified`           | Required verification checks have passed.                                       |
| `partially_verified` | Some verification records have passed while others remain incomplete.           |
| `partially_failed`   | Some verification checks passed and others failed.                              |
| `failed`             | Verification failed. Inspect the failure reason and DNS records.                |
| `temporary_failure`  | Verification could not complete because of a temporary provider or DNS problem. |
| `disabled`           | The domain is not currently available for sending.                              |

## DNS guidance

* Enter DNS names exactly as shown, noting whether your DNS provider automatically appends the zone name.
* Do not proxy email authentication records through an HTTP proxy or CDN.
* Avoid publishing multiple SPF TXT records at the same host.
* Keep DKIM private keys with the sending provider; DNS contains only public verification material.
* Allow time for DNS caches to expire after making changes.

<Tip>
  Use a dedicated sending subdomain when different systems or teams manage product email and corporate mailbox infrastructure.
</Tip>

<CardGroup cols={2}>
  <Card title="Verification" icon="badge-check" href="/docs/domains/verification">
    Check the DNS records required to activate a sender domain.
  </Card>

  <Card title="Regions" icon="globe" href="/docs/domains/regions">
    Choose a supported sending region and TLS mode.
  </Card>

  <Card title="DKIM" icon="key" href="/docs/domains/dkim">
    Learn how DKIM authenticates mail signed for your domain.
  </Card>

  <Card title="SPF" icon="list-check" href="/docs/domains/spf">
    Understand SPF authorization and record management.
  </Card>

  <Card title="DMARC" icon="shield-check" href="/docs/domains/dmarc">
    Add policy and reporting for unauthenticated email.
  </Card>
</CardGroup>