Skip to content
VaartixVaartix Docs

Change a domain's tracking defaults

PATCH
/domains/{id}
curl --request PATCH \
  --url https://api.vaartix.com/domains/dom_5bvatg1v837anztd \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "openTracking": true, "clickTracking": true }'

Turns open and click tracking on or off for emails sent from this domain. Both are off until you turn them on, and each email can override them with tracking. Don’t use click tracking for password reset, magic link or one-time code emails. Owners and admins only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Example 

dom_5bvatg1v837anztd

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
openTracking

Add an open-tracking pixel to HTML emails.

boolean
clickTracking

Rewrite links in HTML emails to count clicks.

boolean

Example generated

{
  "openTracking": true,
  "clickTracking": true
}

Responses

Section titled “Responses”

200

Section titled “200”

The domain.

Media typeapplication/json
object
id
string
name
string
status
string
Allowed values: pending verified failed temporary_failure
region
string
records

The DKIM TXT record (vaartix._domainkey, with the domain’s public key), the MAIL FROM MX and SPF TXT records on the return path (vxmail for new domains, vx-bounces if vxmail was in use and for older domains), and a recommended DMARC TXT record. Domains added before 30 October 2026 show three DKIM CNAME records and send instead.

Array<object>
object
type
string
Allowed values: CNAME MX TXT
name

Full record name.

string
host

The name relative to the registrable domain (by the public suffix list), which is what goes in a DNS provider’s Name or Host field. @ for the registrable domain itself.

string
value
string
priority

MX records only.

integer
status

For the optional DMARC record: verified when a DMARC record was found (on the domain or its registrable domain) at the last check, pending when not, and left out until the domain has been checked once.

string
Allowed values: pending verified failed
optional

True for the recommended DMARC record: it isn’t needed to send, so its status doesn’t affect the domain’s status.

boolean
returnPath

The return-path (MAIL FROM) domain: where bounces go, and what Gmail shows as “mailed-by” under “Show details”. Always vxmail.<domain>, except vx-bounces.<domain> when vxmail was in use, and on domains added before vxmail was the standard (which can move with PUT /domains/{id}/return-path).

string | null
openTracking

Default for emails from this domain. Off unless turned on.

boolean
clickTracking

Default for emails from this domain. Off unless turned on.

boolean
verifiedAt
string | null format: date-time
lastCheckedAt
string | null format: date-time
createdAt
string format: date-time

Example 

{
  "id": "dom_5bvatg1v837anztd",
  "name": "acme.in",
  "status": "pending",
  "region": "ap-south-1",
  "records": [
    {
      "type": "TXT",
      "name": "vaartix._domainkey.acme.in",
      "host": "vaartix._domainkey",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
      "status": "pending"
    },
    {
      "type": "MX",
      "name": "vxmail.acme.in",
      "host": "vxmail",
      "value": "feedback-smtp.ap-south-1.amazonses.com",
      "priority": 10,
      "status": "pending"
    },
    {
      "type": "TXT",
      "name": "vxmail.acme.in",
      "host": "vxmail",
      "value": "v=spf1 include:amazonses.com ~all",
      "status": "pending"
    },
    {
      "type": "TXT",
      "name": "_dmarc.acme.in",
      "host": "_dmarc",
      "value": "v=DMARC1; p=none;"
    }
  ],
  "returnPath": "vxmail.acme.in"
}

400

Section titled “400”

validation_error: the request is invalid. The message says which field and why.

Media typeapplication/json
object
error
required
object
type
required

Stable, machine-readable error type.

string
Allowed values: validation_error unauthorized forbidden not_found conflict rate_limited daily_quota_exceeded domain_not_verified invalid_from_address account_paused domain_needs_review content_rejected idempotency_conflict bad_request internal_error
message
required

Human-readable explanation, safe to show to developers.

string

Example 

{
  "error": {
    "type": "validation_error",
    "message": "to: \"priya@\" is not a valid email address."
  }
}

401

Section titled “401”

unauthorized: the API key is missing, invalid or revoked.

Media typeapplication/json
object
error
required
object
type
required

Stable, machine-readable error type.

string
Allowed values: validation_error unauthorized forbidden not_found conflict rate_limited daily_quota_exceeded domain_not_verified invalid_from_address account_paused domain_needs_review content_rejected idempotency_conflict bad_request internal_error
message
required

Human-readable explanation, safe to show to developers.

string

Example 

{
  "error": {
    "type": "validation_error"
  }
}

403

Section titled “403”

forbidden: the key cannot do this, for example a send-only key on a management endpoint.

Media typeapplication/json
object
error
required
object
type
required

Stable, machine-readable error type.

string
Allowed values: validation_error unauthorized forbidden not_found conflict rate_limited daily_quota_exceeded domain_not_verified invalid_from_address account_paused domain_needs_review content_rejected idempotency_conflict bad_request internal_error
message
required

Human-readable explanation, safe to show to developers.

string

Example 

{
  "error": {
    "type": "validation_error"
  }
}

404

Section titled “404”

not_found: no such resource in your team.

Media typeapplication/json
object
error
required
object
type
required

Stable, machine-readable error type.

string
Allowed values: validation_error unauthorized forbidden not_found conflict rate_limited daily_quota_exceeded domain_not_verified invalid_from_address account_paused domain_needs_review content_rejected idempotency_conflict bad_request internal_error
message
required

Human-readable explanation, safe to show to developers.

string

Example 

{
  "error": {
    "type": "validation_error"
  }
}