Add a domain

POST/api/v1/domains

Requires anorganization API keywith the scopedomains:write

Registers a domain and returns the DNS records to publish. Nothing can be sent from it until those records are live and verification has passed.

Adding a domain does not create any mailboxes. A domain with no mailboxes accepts inbound mail and then has nowhere to put it, so create at least one before pointing MX at us.

Request body

domainstringrequired
The domain to add, like yourdomain.com: no https://, no www..
descriptionstring
Optional. A note for your team, shown in the dashboard.
storage_quotainteger
Optional. Total storage for all mailboxes on this domain, in megabytes.
max_email_accountsinteger
Optional. The most mailboxes this domain may have.
default_email_account_storage_quotainteger
Optional. Storage a new mailbox on this domain gets, in megabytes, unless you give it its own.

Request

POST/api/v1/domains

curl -X POST 'https://app.mailyte.com/api/v1/domains' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "yourdomain.com"
  }'

const response = await fetch('https://app.mailyte.com/api/v1/domains', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mk_live_YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "domain": "yourdomain.com"
  }),
});
const { data } = await response.json();

import requests
response = requests.post(
    "https://app.mailyte.com/api/v1/domains",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={
      "domain": "yourdomain.com"
    },
)
data = response.json()["data"]

<?php

$response = Http::withToken('mk_live_YOUR_API_KEY')
    ->post('https://app.mailyte.com/api/v1/domains', [
    'domain' => 'yourdomain.com',
]);

$data = $response->json('data');

require "net/http"
require "json"
uri = URI("https://app.mailyte.com/api/v1/domains")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer mk_live_YOUR_API_KEY"
request["Content-Type"] = "application/json"
request.body = {
  "domain": "yourdomain.com"
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

The key names its own organization, so no X-Organization-ID header is needed.

Response

Success.

dataobject
- objectstringdomain
- idstring
  Unique identifier for the domain.
- namestring
  The domain itself, e.g. example.com.
- descriptionstring
  Your own note on the domain. Null when none was set.
- statestringactive | provisioning | failed | disabled
  The one lifecycle answer. disabled wins over everything: a disabled domain does nothing whatever its provisioning says.
- provisioningobject
  How far this domain has got on the mail server. This is the detail behind state, not a second answer to it: read state to decide what a domain can do, and this to explain why.
  - statestringpending | provisioning | active | failed | suspended | deleting | deleted
    Where the domain is in setup on the mail server: pending, provisioning, active, failed, suspended, deleting or deleted. For what the domain can do, read state.
  - errorstring
    The last setup or DNS error recorded. Null when there is none. It can be set even on an active domain, so check state or GET /domains/{domain}/verification-status before showing it.
  - retryableboolean
    Whether POST /domains/{domain}/retry-provisioning would do anything. True exactly when state is failed.
- sendingobject
  Sending needs SPF and DKIM. Separate from receiving, because a customer who only relays through us must not publish an MX record.
  - enabledboolean
  - requiresarray<string>
- receivingobject
  Receiving needs MX.
  - enabledboolean
  - requiresarray<string>
- limitsobject
  What this domain is allowed. Every field is always a number. For what the mail server is enforcing right now, use GET /domains/{domain}/limits.
  - storage_bytesinteger
    How many bytes of mail this domain may store in total. The default is 10 GB.
  - max_mailboxesinteger
    How many mailboxes this domain may have. The default is 50.
  - mailboxes_usedinteger
    How many mailboxes the domain has now.
- defaultsobject
  What a NEW mailbox on this domain inherits. Nothing here describes an existing mailbox.
  - mailbox_storage_bytesinteger
    How many bytes of storage each new mailbox gets. The default is 3 GB.
- created_atstring
- updated_atstring

Returned inside the standard envelope.

Errors

Status	When
`401`	The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
`403`	The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.
`404`	No such resource in this organization.
`422`	The request was understood but the values were not acceptable.
`429`	Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.

Every status, with what causes it and what to do, is on the error reference.