Update Domain | AgentMail

{
  "domain_id": "domain_id",
  "domain": "domain",
  "status": "NOT_STARTED",
  "feedback_enabled": true,
  "subdomains_enabled": true,
  "tracking_enabled": true,
  "records": [
    {
      "type": "TXT",
      "name": "name",
      "value": "value",
      "status": "MISSING",
      "priority": 1,
      "reason": "reason"
    },
    {
      "type": "TXT",
      "name": "name",
      "value": "value",
      "status": "MISSING",
      "priority": 1,
      "reason": "reason"
    }
  ],
  "updated_at": "2024-01-15T09:30:00Z",
  "created_at": "2024-01-15T09:30:00Z",
  "pod_id": "pod_id",
  "reason": "reason",
  "inbound_enabled": true,
  "tracking_status": "NOT_STARTED",
  "tracking_reason": "tracking_reason",
  "client_id": "client_id"
}

CLI:

agentmail pods domains update --pod-id <pod_id> --domain-id <domain_id>

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

pod_idstringRequired

ID of pod.

domain_idstringRequired

The ID of the domain.

Request

This endpoint expects an object.

feedback_enabledbooleanOptional

Bounce and complaint notifications are sent to your inboxes.

inbound_enabledbooleanOptional

Receive email for this domain. Defaults to true. Set false for a send-only domain: the apex MX record is not required and is omitted from records, so the domain’s existing email provider keeps receiving its mail. Inboxes on a send-only domain can still send.

subdomains_enabledbooleanOptional

Allow inboxes on any subdomain of this domain. Adds a required wildcard MX record (*.<domain>) to records.

tracking_enabledbooleanOptional

Serve open tracking pixels from this domain. Adds a link.<domain> CNAME record to records. Open tracking reports its readiness in tracking_status and never changes the domain’s status. Sends with track_opens are accepted once tracking_status is VERIFIED.

Response

This endpoint returns an object.

domain_idstring

The ID of the domain.

domainstring

The name of the domain (e.g., example.com).

statusenum

The verification status of the domain.

feedback_enabledboolean

Bounce and complaint notifications are sent to your inboxes.

subdomains_enabledboolean

Allow inboxes on any subdomain of this domain. Adds a required wildcard MX record (*.<domain>) to records.

tracking_enabledboolean

recordslist of objects

A list of DNS records for the domain. Includes the apex MX record unless inbound_enabled is false, and a wildcard MX record (*.<domain>) when subdomains_enabled is true. When tracking_enabled is true it also lists the link.<domain> CNAME and, if the domain’s CAA records restrict issuance, a CAA record. Those two are for open tracking only: they feed tracking_status and do not affect status.

updated_atdatetime

Time at which the domain was last updated.

created_atdatetime

Time at which the domain was created.

pod_idstringOptional

ID of pod.

reasonstringOptional

Why the domain is not (yet) VERIFIED, when known. dns_records_missing / dns_records_invalid point at the DNS records. The ses_* values mean the records look right and sending-infrastructure validation has not converged: ses_dkim_pending / ses_mail_from_pending (still checking), ses_dkim_temporary_failure / ses_mail_from_temporary_failure (a transient error the infrastructure keeps retrying on its own — usually resolves without changes), ses_dkim_failed / ses_mail_from_failed (a terminal verdict; re-verify after fixing), ses_dkim_not_started / ses_mail_from_not_started (the attribute was never configured on the identity — re-verify to push it), ses_not_verified_for_sending, and tracking_certificate_failed (the certificate for the open tracking link. subdomain was refused; fix CAA or DNS, then turn tracking off and back on). Absent when VERIFIED.

inbound_enabledbooleanOptional

Absent on domains created before this field existed; those receive email.

tracking_statusenumOptional

Present when tracking_enabled is true.

tracking_reasonstringOptional

Why open tracking is not (yet) VERIFIED, when known. dns_records_missing / dns_records_invalid point at the link.<domain> CNAME. caa_blocked means the domain’s CAA records leave Amazon out: add the CAA record listed in records, and AgentMail retries the certificate on its own within a few minutes. certificate_failed means the certificate was refused; fix the DNS, then turn tracking off and back on. Absent when tracking_status is VERIFIED.

client_idstringOptional

Client ID of domain.

Errors

404

Not Found Error