---
title: "Set your default mail server name"
method: PUT
path: "/mail-host"
tags: ["Partners"]
---

# Set your default mail server name

`PUT /mail-host`

## Request

- Base URL: `https://faivelo.com/api/partner`
- URL: `https://faivelo.com/api/partner/mail-host`
- Auth: HTTP bearer

Sets or renames your default name (adds one when you have none). Name a host under your own domain (`mail.yourcompany.com`) and publish an A record from it to Faivelo's mail proxy (the address in `status.setup.value`), with no other A or AAAA record for the name. The DNS check runs at once; the proxy then issues and renews the certificate on its own. Customers switch to the name only when both `dns.verified` and `certificate.valid` are true. Requires `partner:write`.

## Request body

- object
  - `host` string, required

## Response `200`

The host and the check results

- object
  - `success` boolean
  - `data` PartnerMailHostCheck
    - `status` PartnerMailHost: One of your white-label mail server names and whether customers see it yet
      - `id` string, nullable: Null only on the empty answer of GET /mail-host when you have no default
      - `host` string, nullable
      - `isDefault` boolean: Your default name: what customers without their own pick see
      - `activeHost` string: What customers see right now: your host once live, else mx.faivelo.com
      - `live` boolean: DNS points at the proxy and the proxy serves a valid certificate for the name
      - `dns` object
        - `verified` boolean
        - `checkedAt` string, date-time, nullable
      - `certificate` object
        - `valid` boolean
        - `checkedAt` string, date-time, nullable
        - `expiresAt` string, date-time, nullable
        - `daysLeft` integer, nullable
      - `error` string, nullable: Why the last check failed, in plain words
      - `setup` object, nullable: The one record to publish: an A record from the host to the mail proxy
        - `type` 'A' | 'CNAME': A; CNAME only on a deployment without a proxy, where no host can go live
        - `name` string
        - `value` string
      - `ports` object: The ports customers get with activeHost
        - `imapPort` integer
        - `smtpPort` integer: 465 (SSL/TLS) on a live partner host, 587 (STARTTLS) on mx.faivelo.com
        - `smtpSecurity` 'ssl' | 'starttls'
      - `createdAt` string, date-time, nullable
    - `dns` object
      - `ok` boolean
      - `reason` string
    - `certificate` object
      - `ok` boolean
      - `reason` string
      - `daysLeft` integer, nullable

## Other responses

- `400`: Enter a hostname under your own domain
- `401`: Missing or invalid API key, or not a partner key
- `403`: The key lacks the required scope, or provisioning is refused (partner paused, customer cap reached)
- `404`: Not found, including any customer that is not yours
- `409`: That hostname is already in use
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/faivelo/apis/faivelo-api.md) · [All operations](https://skmtc.dev/faivelo/apis/faivelo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/faivelo/apis/faivelo-api/revisions/a7413ddea5d1?raw)