For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
  • FreeCustom.Email API
        • GETList your custom domains
        • POSTAdd a custom domain
LogoLogo
FreeCustom.Email APIV1Custom Domains

Add a custom domain

||View as Markdown|
POST
https://api2.freecustom.email/v1/custom-domains
POST
/v1/custom-domains
$curl -X POST https://api2.freecustom.email/v1/custom-domains \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "domain": "mail.acme.com"
>}'
1{
2  "success": true,
3  "message": "Domain already added.",
4  "data": {
5    "domain": "mail.acme.com",
6    "verified": true,
7    "mx_record": "mx.freecustom.email",
8    "txt_record": "freecustomemail-verification=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
9    "added_at": "2026-01-15T10:00:00.000Z"
10  }
11}
Adds a new custom domain to your account and returns the DNS records you must configure at your registrar before verifying. **Plan required:** Growth ($49/mo) or Enterprise ($149/mo). **Workflow:** 1. `POST /v1/custom-domains` — add the domain, get DNS records. 2. Add the two DNS records (MX + TXT) at your registrar. 3. `POST /v1/custom-domains/{domain}/verify` — confirm propagation. 4. `POST /v1/inboxes` with any address `@yourdomain` — start receiving mail. This call is **idempotent** — if the domain is already added it returns the existing entry with `200` instead of `201`. **Limits:** Maximum 10 custom domains per account.
Was this page helpful?
Previous

List your custom domains

Next

Remove a custom domain

Built with

Adds a new custom domain to your account and returns the DNS records you must configure at your registrar before verifying.

Plan required: Growth (49/mo)orEnterprise(49/mo) or Enterprise (49/mo)orEnterprise(149/mo).

Workflow:

  1. POST /v1/custom-domains — add the domain, get DNS records.
  2. Add the two DNS records (MX + TXT) at your registrar.
  3. POST /v1/custom-domains/{domain}/verify — confirm propagation.
  4. POST /v1/inboxes with any address @yourdomain — start receiving mail.

This call is idempotent — if the domain is already added it returns the existing entry with 200 instead of 201.

Limits: Maximum 10 custom domains per account.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
domainstringRequired

Response

OK
successboolean
messagestring
dataobject

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error