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.
# 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"Before you start
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 — the send pipeline.
- Templates and merge tags — compose the body.