Email

Project email goes out from Amba's shared mailbox until the project adds a sending domain and it verifies. A domain the project bought through Amba is Amba-managed (dns_managed: true): Amba writes its DNS records, starts verification, and keeps checking, so there is no DNS step. Any other domain is self-hosted (dns_managed: false): you create the returned records at your DNS host, then call verify. The email guide walks through both paths. Templates, suppressions, sends, and deliveries are described in the email guide.

Sender choice happens on the server. The client SDKs need no change: passwordless sign-in email (one-time codes and magic links) uses the project's default sender once it is set.

Endpoints

The sending-domain object

Every domain endpoint returns this shape (inside data).

Record

POST /admin/projects/:projectId/email/domains

Add a sending domain.

• Amba-managed (one of this project's domains bought through Amba, or a subdomain of one): Amba writes the DKIM TXT record, the send. MX and SPF TXT records, any return-path CNAME (such as rsend.example.com), and _dmarc TXT v=DMARC1; p=none; when the domain has no DMARC policy, then starts verification once every record is in DNS and schedules automatic checks. Identical existing records are left alone, the domain's root MX and SPF records (email forwarding) are never touched, and an existing DMARC policy is kept.
• Self-hosted (any other domain): Amba registers the domain and returns the records to create. Nothing is written to DNS.

Request

Response 201 (Amba-managed)

{
  "data": {
    "domain": "example.com",
    "status": "pending",
    "dns_managed": true,
    "dns_status": "published",
    "dns_error": null,
    "records": [
      {
        "record": "DKIM",
        "type": "TXT",
        "name": "<selector>._domainkey.example.com",
        "value": "p=…",
        "status": "pending",
        "publish_state": "published",
        "created_by_amba": true,
        "conflict": null
      },
      {
        "record": "SPF",
        "type": "MX",
        "name": "send.example.com",
        "value": "…",
        "priority": 10,
        "status": "pending",
        "publish_state": "published",
        "created_by_amba": true,
        "conflict": null
      },
      {
        "record": "SPF",
        "type": "TXT",
        "name": "send.example.com",
        "value": "v=spf1 …",
        "status": "pending",
        "publish_state": "published",
        "created_by_amba": true,
        "conflict": null
      },
      {
        "record": "SPF",
        "type": "CNAME",
        "name": "rsend.example.com",
        "value": "…",
        "status": "pending",
        "publish_state": "published",
        "created_by_amba": true,
        "conflict": null
      },
      {
        "record": "DMARC",
        "type": "TXT",
        "name": "_dmarc.example.com",
        "value": "v=DMARC1; p=none;",
        "publish_state": "published",
        "created_by_amba": true,
        "conflict": null
      }
    ],
    "recommended_dmarc": null,
    "default_sender_fallback": false,
    "verified_at": null,
    "next_check_at": "2026-10-09T12:01:00.000Z",
    "checks_until": "2026-10-12T12:00:00.000Z",
    "next_step": "No DNS action needed. Amba published the DNS records and the domain is waiting for verification. Amba checks verification automatically until 2026-10-12T12:00:00.000Z."
  }
}

Response 201 (self-hosted)

{
  "data": {
    "domain": "example.org",
    "status": "pending",
    "dns_managed": false,
    "dns_status": null,
    "records": [
      {
        "record": "SPF",
        "type": "TXT",
        "name": "send.example.org",
        "value": "v=spf1 …",
        "status": "not_started",
        "publish_state": null,
        "created_by_amba": false,
        "conflict": null
      }
    ],
    "recommended_dmarc": {
      "record": "DMARC",
      "type": "TXT",
      "name": "_dmarc.example.org",
      "value": "v=DMARC1; p=none;"
    },
    "next_check_at": null,
    "next_step": "Create the records listed in records and the recommended_dmarc record at your DNS host, then call verify. …"
  }
}

Errors

• 400 INVALID_JSON / 400 INVALID_DOMAIN — the body or domain is malformed.
• 409 DOMAIN_CLAIMED — the domain belongs to another project: it was added there first, or another project bought it through Amba.
• 409 DNS_RECORD_CONFLICT — Amba-managed: a record Amba did not create holds a name Amba needs (another SPF policy on send., another DKIM key at the selector, a CNAME at a TXT or MX name, or any record at the name of a return-path CNAME other than that same CNAME). The message names each record; Amba leaves it unchanged. The domain is added anyway and returned in error.details.domain. If a site or function domain on this project uses that name, remove that domain; otherwise contact Amba support to have the record removed. Then call verify.
• 502 EMAIL_PROVIDER_REJECTED / 503 EMAIL_PROVIDER_UNAVAILABLE — the domain could not be registered; retry.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/email/domains' \
  -H 'Content-Type: application/json' \
  -d '{
  "domain": "mail.example.com"
}'

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/email/domains" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"domain":"mail.example.com"}'

GET /admin/projects/:projectId/email/domains

List the project's sending domains, refreshing each one's verification status.

Response 200

{
  "data": [
    {
      "domain": "example.com",
      "status": "verified",
      "dns_managed": true,
      "next_step": "Verified. …"
    }
  ]
}

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/email/domains'

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/email/domains" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

GET /admin/projects/:projectId/email/domains/:domain

Refresh one sending domain. Reads only: it never writes DNS.

Response 200

The sending-domain object.

Errors

• 404 DOMAIN_NOT_FOUND.

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/email/domains/%7B%7Bdomain%7D%7D'

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/email/domains/{domain}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

POST /admin/projects/:projectId/email/domains/:domain/verify

Start verification and restart the 72-hour window of automatic checks.

• Amba-managed: first re-publishes any record that is not in DNS yet (and adopts a domain that was added before its purchase completed), then starts verification once every record is published.
• Self-hosted: call this after creating the records. Amba keeps checking automatically until the domain verifies or the window ends.

When the window ends unverified, the domain stays pending, next_check_at becomes null, and next_step asks you to call verify again. On the transition to verified, Amba emits the email.domain.verified control event ({ "domain": "example.com", "dns_managed": true }) to subscribed control webhooks.

Response 200

The sending-domain object.

Errors

• 404 DOMAIN_NOT_FOUND.
• 409 DNS_RECORD_CONFLICT — as for add.
• 502 EMAIL_PROVIDER_REJECTED / 503 EMAIL_PROVIDER_UNAVAILABLE — the verification request failed; retry.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/email/domains/%7B%7Bdomain%7D%7D/verify'

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/email/domains/{domain}/verify" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/email/domains/:domain

Remove a sending domain. For an Amba-managed domain, Amba deletes the DNS records it created; every other record (your own records, an existing DMARC policy, email forwarding) stays as it is. If the project default sender used this domain, email falls back to the shared mailbox.

Response 200

{ "data": { "deleted": true } }

Errors

• 404 DOMAIN_NOT_FOUND.
• 502 DNS_CLEANUP_FAILED — the records Amba created could not be deleted. Nothing was removed; retry.

Try it:

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/email/domains/%7B%7Bdomain%7D%7D'

Curl:

curl -X DELETE "${BASE_URL}/admin/projects/${PROJECT_ID}/email/domains/{domain}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

POST /admin/projects/:projectId/email/send

Send a templated or ad-hoc email. The full body is described in the email guide. Sender fields:

Errors

• 400 INVALID_SENDER — from.email is not on a verified sending domain of this project. Nothing is sent.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/email/send' \
  -H 'Content-Type: application/json' \
  -d '{
  "to": {
    "email": "user@example.com"
  },
  "subject": "Welcome",
  "text": "Thanks for signing up."
}'

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/email/send" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"to":{"email":"user@example.com"},"subject":"Welcome","text":"Thanks for signing up."}'