Skip to content
VaartixVaartix Docs

Move the return path to vxmail

PUT
/domains/{id}/return-path
curl --request PUT \
  --url https://api.vaartix.com/domains/dom_5bvatg1v837anztd/return-path \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "subdomain": "vxmail" }'

Moves a domain added before vxmail was the standard (on vx-bounces, or a subdomain chosen back then) to vxmail., so Gmail’s “Show details” shows “mailed-by vxmail.acme.in”. The return path can’t be anything else: other values are refused (400), and asking for vxmail on a domain already there changes nothing. Publish the new MX and TXT records the response lists; sending carries on meanwhile, with Amazon SES’s own return path until they verify. Refused (409) if vxmail. already has MX records (pointing it at Vaartix would stop it receiving email), a CNAME or an SPF record. 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
subdomain
required

Always vxmail (vxmail.<domain> is accepted too).

string
Allowed values: vxmail

Example 

vxmail

Responses

Section titled “Responses”

200

Section titled “200”

The domain, with the new return-path records.

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"
  }
}

409

Section titled “409”

conflict: the request clashes with the current state, for example too many endpoints.

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"
  }
}