---
title: "Add a mail server name"
method: POST
path: "/mail-hosts"
tags: ["Partners"]
---

# Add a mail server name

`POST /mail-hosts`

## Request

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

Add a name under a domain you control and publish the A record in `status.setup`. The first name becomes your default; pass `default: true` to make a later one the default. The DNS check runs at once; the proxy issues the certificate on its own. Requires `partner:write`.

## Request body

- object
  - `host` string, required
  - `default` boolean

## Response `200`

The name 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, or the account holds the maximum of 25 names
- `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)