# Move the return path to vxmail

> Documentation and API reference for Vaartix, the email API for Indian developers.

Source: https://vaartix.com/docs/api/operations/setreturnpath/

PUT

/domains/{id}/return-path

```sh
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

-   **[apiKey](https://vaartix.com/docs/api/#apikey)**

## Parameters

### Path Parameters

**id**

required

string

#### Example

```
dom_5bvatg1v837anztd
```

## Request Bodyrequired

Media typeapplication/json

**object**

**subdomain**

required

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

string

Allowed values: vxmail

### Example

```
vxmail
```

## Responses

### 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

```json
{
  "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

`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

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

### 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

```json
{
  "error": {
    "type": "validation_error"
  }
}
```

### 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

```json
{
  "error": {
    "type": "validation_error"
  }
}
```

### 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

```json
{
  "error": {
    "type": "validation_error"
  }
}
```

### 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

```json
{
  "error": {
    "type": "validation_error"
  }
}
```