# Sending domains

Add a domain, publish the DNS records, and verify it before the first campaign send.

Mail sends from an address on a verified domain. Adding a domain returns the DNS
records to publish; verification checks them and unlocks sending.

```bash
# 1. Add the domain
curl -X POST https://api.console.buildbase.app/api/emails/domains \
  -H "Authorization: $BUILDBASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'

# 2. Publish the returned records in DNS, then verify
curl -X POST https://api.console.buildbase.app/api/emails/domains/$DOMAIN_ID/verify \
  -H "Authorization: $BUILDBASE_TOKEN"
```

> **Note:**
  Domain verification is Mailgun-backed. A sending domain requires Mailgun to be
  configured for the organization even when a given sender delivers through
  Google, Mailgun, and custom SMTP
  .


## Records

Creating a domain stores two record sets returned by Mailgun:

| Set                   | Purpose                                                        |
| --------------------- | -------------------------------------------------------------- |
| **Sending records**   | Authorize BuildBase to send as the domain. Publish all of them |
| **Receiving records** | `MX` records, needed only if the domain should receive mail    |

Publish every sending record exactly as returned. The console lists them with
their type, name, and value, ready to copy into your DNS provider.

A subdomain such as `mail.example.com` is the usual choice — it keeps sending
reputation and DNS separate from your apex domain.

## Verifying

`POST /api/emails/domains/:id/verify` re-checks DNS and returns the updated
domain document.

| Outcome                                  | Response                                          |
| ---------------------------------------- | ------------------------------------------------- |
| Verified                                 | `200` with the domain object                      |
| Not yet propagated, or a record is wrong | `400` with `{ "success": false, "message": "…" }` |

The `400` uses `success: false`, unlike most API errors which use `error: true`.

Verification is not automatic — nothing retries it in the background. Call it
again after DNS propagates, which typically takes minutes but can take hours
depending on your provider's TTL.

A successful verification emits `email.domain.verified`, so a workflow can
notify the team rather than having someone poll the console.

## Endpoints

| Method | Path                             | Purpose                           |
| ------ | -------------------------------- | --------------------------------- |
| `GET`  | `/api/emails/domains`            | List domains, paginated           |
| `GET`  | `/api/emails/domains/:id`        | One domain, including its records |
| `POST` | `/api/emails/domains`            | Add a domain                      |
| `POST` | `/api/emails/domains/:id/verify` | Re-check DNS                      |

## Senders

A sender is an address on a verified domain. One sender per organization can be
marked default, and it is used when a campaign names none. A Google sender is
connected through an OAuth callback rather than a stored password.

Access is enforced at three distinct levels — sharing a sender does not hand
over control of it:

| Action                              | Who can do it                      |
| ----------------------------------- | ---------------------------------- |
| List senders                        | Owner, or anyone it is shared with |
| Read one sender                     | Owner, or anyone it is shared with |
| Update, delete, set as default      | Owner only                         |
| Share, unshare, manage shared users | **Creator only**                   |

The creator/owner split is the part worth noting: someone can own a sender well
enough to send from it and change it, and still not be able to change who else
it is shared with.

## Next Steps

- [Campaigns overview](/email/overview) — the send pipeline.
- [Templates and merge tags](/email/templates-and-merge-tags) — compose the body.