AGagentmail-to
pods > domains

Update Domain

Changed on

CLI:

agentmail pods domains update --pod-id <pod_id> --domain-id <domain_id>
patch/v0/pods/{pod_id}/domains/{domain_id}

Request

  • Base URL
    https://api.agentmail.to
  • URL
    https://api.agentmail.to/v0/pods/{pod_id}/domains/{domain_id}
  • Auth
    HTTP bearer

Path parameters

pod_idstring required

ID of pod.

domain_idstring required

The ID of the domain.

Request body

feedback_enabledboolean

Bounce and complaint notifications are sent to your inboxes.

inbound_enabledboolean

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_enabledboolean

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

tracking_enabledboolean

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

Response with status 200

pod_idstring

ID of pod.

domain_idstring required

The ID of the domain.

domainstring required

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

status'NOT_STARTED' | 'PENDING' | 'INVALID' | 'FAILED' | 'VERIFYING' | 'VERIFIED' required
reasonstring

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.

feedback_enabledboolean required

Bounce and complaint notifications are sent to your inboxes.

inbound_enabledboolean

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_enabledboolean required

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

tracking_enabledboolean required

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.

tracking_status'NOT_STARTED' | 'PENDING' | 'INVALID' | 'FAILED' | 'VERIFYING' | 'VERIFIED'
tracking_reasonstring

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_idstring

Client ID of domain.

updated_atstring date-time required

Time at which the domain was last updated.

created_atstring date-time required

Time at which the domain was created.

Changes

  • 4d380313b7beRevision changes
    • warning

      added the new CAA enum value to the // response property for the response status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 3f5c7830c952Revision changes
    • breaking

      the request property became not nullable

    • breaking

      the request property became not nullable

    • info

      the endpoint scheme security Bearer was added to the API

    • info

      the endpoint scheme security BearerAuth was removed from the API

    • info

      api tag pods > domains added

    • info

      api tag PodsDomains removed

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      request body became optional

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the required property to the response with the status