Domains

GET `/domains`

List the domains the organization has added, alphabetically by default. Supports cursor pagination.

Requires the settings:read permission.

Query parameters

limitnumber

The number of records to return.

cursorstring

A pagination cursor. Fetch the next page by passing the nextCursor value from the previous response.

sortdomain | -domain | createdAt | -createdAt

The sort order. Prefix a field with - to sort descending. Defaults to domain.

Request

curl \
  "https://your-store.meisei.app/api/domains" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getDomains } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getDomains()

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

page = meisei.domains.list

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

page = meisei.domains.list()

Response

{
  "data": [
    {
      "id": "A4Ws1igz",
      "domain": "string",
      "verificationToken": "string",
      "verifiedAt": "2025-01-15T09:30:00Z",
      "emailProvider": "string",
      "emailVerifiedAt": "2025-01-15T09:30:00Z",
      "records": ["..."],
      "lastCheckedAt": "2025-01-15T09:30:00Z",
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    }
  ],
  "nextCursor": "string"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the domain.",
            "idCodec": "sqid"
          },
          "domain": {
            "type": "string",
            "description": "The domain name, lowercase and without a trailing dot."
          },
          "verificationToken": {
            "type": "string",
            "description": "The value the ownership TXT record has to hold, after `meisei-verification=`."
          },
          "verifiedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the ownership record was first seen, or null if it has not been yet."
          },
          "emailProvider": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Which email provider holds this domain, or null if email setup has not started."
          },
          "emailVerifiedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When the email provider finished verifying the domain, or null if it has not finished."
          },
          "records": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": ["TXT", "CNAME", "MX"],
                  "description": "The type of DNS record to create."
                },
                "name": {
                  "type": "string",
                  "description": "The fully qualified host the record goes on."
                },
                "value": {
                  "type": "string",
                  "description": "The value the record has to hold."
                },
                "purpose": {
                  "type": "string",
                  "enum": ["dkim", "return-path", "spf", "ownership", "pages", "acme"],
                  "description": "What the record is for: `dkim` and `return-path` for sending email, `spf` for the sender policy, `ownership` for proving you control the domain, `pages` for pointing a hostname at Meisei, and `acme` for issuing its certificate."
                },
                "verified": {
                  "type": "boolean",
                  "description": "Whether the record has been seen in DNS yet."
                }
              },
              "required": ["type", "name", "value", "purpose", "verified"],
              "additionalProperties": false
            },
            "description": "Every DNS record the domain needs: the ownership record first, then whatever the email provider asked for."
          },
          "lastCheckedAt": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
              },
              {
                "type": "null"
              }
            ],
            "description": "When Meisei last checked this domain's records."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the domain was added."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
            "description": "When the domain was last changed."
          }
        },
        "required": [
          "id",
          "domain",
          "verificationToken",
          "verifiedAt",
          "emailProvider",
          "emailVerifiedAt",
          "records",
          "lastCheckedAt",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      },
      "description": "The page of records, in the requested sort order."
    },
    "nextCursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Pass this back as `cursor` to fetch the next page. Null once the last page has been returned."
    }
  },
  "required": ["data", "nextCursor"],
  "additionalProperties": false
}

POST `/domains`

Add a domain you own. The response carries the TXT record to create; once it is in place, call POST /domains/:id/verify. Fails if another account has already claimed the domain.

Requires the settings:write permission.

Body parameters

domainstringrequired

The domain or subdomain you own, such as example.com or shop.example.com. Leave off the scheme, the port and any path.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/domains" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "string"
}'

Request

import { client } from "@meisei/api/admin/client"
import { postDomains } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postDomains({
  body: {
    domain: "string",
  },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.domains.create(domain: "string")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.domains.create(domain="string")

Response

{
  "id": "A4Ws1igz",
  "domain": "string",
  "verificationToken": "string",
  "verifiedAt": "2025-01-15T09:30:00Z",
  "emailProvider": "string",
  "emailVerifiedAt": "2025-01-15T09:30:00Z",
  "records": [
    {
      "type": "TXT",
      "name": "string",
      "value": "string",
      "purpose": "dkim",
      "verified": true
    }
  ],
  "lastCheckedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the domain.",
      "idCodec": "sqid"
    },
    "domain": {
      "type": "string",
      "description": "The domain name, lowercase and without a trailing dot."
    },
    "verificationToken": {
      "type": "string",
      "description": "The value the ownership TXT record has to hold, after `meisei-verification=`."
    },
    "verifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the ownership record was first seen, or null if it has not been yet."
    },
    "emailProvider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Which email provider holds this domain, or null if email setup has not started."
    },
    "emailVerifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the email provider finished verifying the domain, or null if it has not finished."
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["TXT", "CNAME", "MX"],
            "description": "The type of DNS record to create."
          },
          "name": {
            "type": "string",
            "description": "The fully qualified host the record goes on."
          },
          "value": {
            "type": "string",
            "description": "The value the record has to hold."
          },
          "purpose": {
            "type": "string",
            "enum": ["dkim", "return-path", "spf", "ownership", "pages", "acme"],
            "description": "What the record is for: `dkim` and `return-path` for sending email, `spf` for the sender policy, `ownership` for proving you control the domain, `pages` for pointing a hostname at Meisei, and `acme` for issuing its certificate."
          },
          "verified": {
            "type": "boolean",
            "description": "Whether the record has been seen in DNS yet."
          }
        },
        "required": ["type", "name", "value", "purpose", "verified"],
        "additionalProperties": false
      },
      "description": "Every DNS record the domain needs: the ownership record first, then whatever the email provider asked for."
    },
    "lastCheckedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When Meisei last checked this domain's records."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was added."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was last changed."
    }
  },
  "required": [
    "id",
    "domain",
    "verificationToken",
    "verifiedAt",
    "emailProvider",
    "emailVerifiedAt",
    "records",
    "lastCheckedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The new domain, with the record to create."
}

GET `/domains/{id}`

Get a single domain by ID, with every DNS record it needs.

Requires the settings:read permission.

Path parameters

idstringrequired

The ID of the domain.

Request

curl \
  "https://your-store.meisei.app/api/domains/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { getDomainsById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await getDomainsById({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.domains.retrieve("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.domains.retrieve("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "domain": "string",
  "verificationToken": "string",
  "verifiedAt": "2025-01-15T09:30:00Z",
  "emailProvider": "string",
  "emailVerifiedAt": "2025-01-15T09:30:00Z",
  "records": [
    {
      "type": "TXT",
      "name": "string",
      "value": "string",
      "purpose": "dkim",
      "verified": true
    }
  ],
  "lastCheckedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the domain.",
      "idCodec": "sqid"
    },
    "domain": {
      "type": "string",
      "description": "The domain name, lowercase and without a trailing dot."
    },
    "verificationToken": {
      "type": "string",
      "description": "The value the ownership TXT record has to hold, after `meisei-verification=`."
    },
    "verifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the ownership record was first seen, or null if it has not been yet."
    },
    "emailProvider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Which email provider holds this domain, or null if email setup has not started."
    },
    "emailVerifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the email provider finished verifying the domain, or null if it has not finished."
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["TXT", "CNAME", "MX"],
            "description": "The type of DNS record to create."
          },
          "name": {
            "type": "string",
            "description": "The fully qualified host the record goes on."
          },
          "value": {
            "type": "string",
            "description": "The value the record has to hold."
          },
          "purpose": {
            "type": "string",
            "enum": ["dkim", "return-path", "spf", "ownership", "pages", "acme"],
            "description": "What the record is for: `dkim` and `return-path` for sending email, `spf` for the sender policy, `ownership` for proving you control the domain, `pages` for pointing a hostname at Meisei, and `acme` for issuing its certificate."
          },
          "verified": {
            "type": "boolean",
            "description": "Whether the record has been seen in DNS yet."
          }
        },
        "required": ["type", "name", "value", "purpose", "verified"],
        "additionalProperties": false
      },
      "description": "Every DNS record the domain needs: the ownership record first, then whatever the email provider asked for."
    },
    "lastCheckedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When Meisei last checked this domain's records."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was added."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was last changed."
    }
  },
  "required": [
    "id",
    "domain",
    "verificationToken",
    "verifiedAt",
    "emailProvider",
    "emailVerifiedAt",
    "records",
    "lastCheckedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The requested domain."
}

DELETE `/domains/{id}`

Remove a domain. Its custom hostnames go with it, and any site sending from it goes back to sending through Meisei.

Requires the settings:write permission.

Path parameters

idstringrequired

The ID of the domain to remove.

Request

curl \
  -X DELETE \
  "https://your-store.meisei.app/api/domains/A4Ws1igz" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { deleteDomainsById } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await deleteDomainsById({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.domains.delete("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.domains.delete("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "domain": "string",
  "verificationToken": "string",
  "verifiedAt": "2025-01-15T09:30:00Z",
  "emailProvider": "string",
  "emailVerifiedAt": "2025-01-15T09:30:00Z",
  "records": [
    {
      "type": "TXT",
      "name": "string",
      "value": "string",
      "purpose": "dkim",
      "verified": true
    }
  ],
  "lastCheckedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the domain.",
      "idCodec": "sqid"
    },
    "domain": {
      "type": "string",
      "description": "The domain name, lowercase and without a trailing dot."
    },
    "verificationToken": {
      "type": "string",
      "description": "The value the ownership TXT record has to hold, after `meisei-verification=`."
    },
    "verifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the ownership record was first seen, or null if it has not been yet."
    },
    "emailProvider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Which email provider holds this domain, or null if email setup has not started."
    },
    "emailVerifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the email provider finished verifying the domain, or null if it has not finished."
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["TXT", "CNAME", "MX"],
            "description": "The type of DNS record to create."
          },
          "name": {
            "type": "string",
            "description": "The fully qualified host the record goes on."
          },
          "value": {
            "type": "string",
            "description": "The value the record has to hold."
          },
          "purpose": {
            "type": "string",
            "enum": ["dkim", "return-path", "spf", "ownership", "pages", "acme"],
            "description": "What the record is for: `dkim` and `return-path` for sending email, `spf` for the sender policy, `ownership` for proving you control the domain, `pages` for pointing a hostname at Meisei, and `acme` for issuing its certificate."
          },
          "verified": {
            "type": "boolean",
            "description": "Whether the record has been seen in DNS yet."
          }
        },
        "required": ["type", "name", "value", "purpose", "verified"],
        "additionalProperties": false
      },
      "description": "Every DNS record the domain needs: the ownership record first, then whatever the email provider asked for."
    },
    "lastCheckedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When Meisei last checked this domain's records."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was added."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was last changed."
    }
  },
  "required": [
    "id",
    "domain",
    "verificationToken",
    "verifiedAt",
    "emailProvider",
    "emailVerifiedAt",
    "records",
    "lastCheckedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The domain that was removed."
}

POST `/domains/{id}/verify`

Check the domain's DNS records now. It looks for the ownership record if the domain is not verified yet, and asks the email provider how email setup is going if it has been started.

Requires the settings:write permission.

Costs 5 rate limit tokens instead of the usual one. See Rate limits.

Path parameters

idstringrequired

The ID of the domain to check.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/domains/A4Ws1igz/verify" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { postDomainsByIdVerify } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postDomainsByIdVerify({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.domains.verify("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.domains.verify("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "domain": "string",
  "verificationToken": "string",
  "verifiedAt": "2025-01-15T09:30:00Z",
  "emailProvider": "string",
  "emailVerifiedAt": "2025-01-15T09:30:00Z",
  "records": [
    {
      "type": "TXT",
      "name": "string",
      "value": "string",
      "purpose": "dkim",
      "verified": true
    }
  ],
  "lastCheckedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the domain.",
      "idCodec": "sqid"
    },
    "domain": {
      "type": "string",
      "description": "The domain name, lowercase and without a trailing dot."
    },
    "verificationToken": {
      "type": "string",
      "description": "The value the ownership TXT record has to hold, after `meisei-verification=`."
    },
    "verifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the ownership record was first seen, or null if it has not been yet."
    },
    "emailProvider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Which email provider holds this domain, or null if email setup has not started."
    },
    "emailVerifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the email provider finished verifying the domain, or null if it has not finished."
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["TXT", "CNAME", "MX"],
            "description": "The type of DNS record to create."
          },
          "name": {
            "type": "string",
            "description": "The fully qualified host the record goes on."
          },
          "value": {
            "type": "string",
            "description": "The value the record has to hold."
          },
          "purpose": {
            "type": "string",
            "enum": ["dkim", "return-path", "spf", "ownership", "pages", "acme"],
            "description": "What the record is for: `dkim` and `return-path` for sending email, `spf` for the sender policy, `ownership` for proving you control the domain, `pages` for pointing a hostname at Meisei, and `acme` for issuing its certificate."
          },
          "verified": {
            "type": "boolean",
            "description": "Whether the record has been seen in DNS yet."
          }
        },
        "required": ["type", "name", "value", "purpose", "verified"],
        "additionalProperties": false
      },
      "description": "Every DNS record the domain needs: the ownership record first, then whatever the email provider asked for."
    },
    "lastCheckedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When Meisei last checked this domain's records."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was added."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was last changed."
    }
  },
  "required": [
    "id",
    "domain",
    "verificationToken",
    "verifiedAt",
    "emailProvider",
    "emailVerifiedAt",
    "records",
    "lastCheckedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The domain as it now stands."
}

POST `/domains/{id}/email`

Start setting the domain up to send email. The response carries the DKIM and return-path records to create. The domain's ownership has to be verified first.

Requires the settings:write permission.

Costs 5 rate limit tokens instead of the usual one. See Rate limits.

Path parameters

idstringrequired

The ID of the domain.

Request

curl \
  -X POST \
  "https://your-store.meisei.app/api/domains/A4Ws1igz/email" \
  -H "Authorization: Bearer sk_YOUR_SECRET_KEY"

Request

import { client } from "@meisei/api/admin/client"
import { postDomainsByIdEmail } from "@meisei/api/admin"

client.setConfig({
  baseUrl: "https://your-store.meisei.app/api",
  headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})

const { data, error } = await postDomainsByIdEmail({
  path: { id: "A4Ws1igz" },
})

Request

require "meisei"

meisei = Meisei::Client.new(
  secret_key: "sk_YOUR_SECRET_KEY",
  base_url: "https://your-store.meisei.app/api",
)

result = meisei.domains.enable_email("A4Ws1igz")

Request

from meisei import Client

meisei = Client(
    secret_key="sk_YOUR_SECRET_KEY",
    base_url="https://your-store.meisei.app/api",
)

result = meisei.domains.enable_email("A4Ws1igz")

Response

{
  "id": "A4Ws1igz",
  "domain": "string",
  "verificationToken": "string",
  "verifiedAt": "2025-01-15T09:30:00Z",
  "emailProvider": "string",
  "emailVerifiedAt": "2025-01-15T09:30:00Z",
  "records": [
    {
      "type": "TXT",
      "name": "string",
      "value": "string",
      "purpose": "dkim",
      "verified": true
    }
  ],
  "lastCheckedAt": "2025-01-15T09:30:00Z",
  "createdAt": "2025-01-15T09:30:00Z",
  "updatedAt": "2025-01-15T09:30:00Z"
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the domain.",
      "idCodec": "sqid"
    },
    "domain": {
      "type": "string",
      "description": "The domain name, lowercase and without a trailing dot."
    },
    "verificationToken": {
      "type": "string",
      "description": "The value the ownership TXT record has to hold, after `meisei-verification=`."
    },
    "verifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the ownership record was first seen, or null if it has not been yet."
    },
    "emailProvider": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Which email provider holds this domain, or null if email setup has not started."
    },
    "emailVerifiedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When the email provider finished verifying the domain, or null if it has not finished."
    },
    "records": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["TXT", "CNAME", "MX"],
            "description": "The type of DNS record to create."
          },
          "name": {
            "type": "string",
            "description": "The fully qualified host the record goes on."
          },
          "value": {
            "type": "string",
            "description": "The value the record has to hold."
          },
          "purpose": {
            "type": "string",
            "enum": ["dkim", "return-path", "spf", "ownership", "pages", "acme"],
            "description": "What the record is for: `dkim` and `return-path` for sending email, `spf` for the sender policy, `ownership` for proving you control the domain, `pages` for pointing a hostname at Meisei, and `acme` for issuing its certificate."
          },
          "verified": {
            "type": "boolean",
            "description": "Whether the record has been seen in DNS yet."
          }
        },
        "required": ["type", "name", "value", "purpose", "verified"],
        "additionalProperties": false
      },
      "description": "Every DNS record the domain needs: the ownership record first, then whatever the email provider asked for."
    },
    "lastCheckedAt": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
        },
        {
          "type": "null"
        }
      ],
      "description": "When Meisei last checked this domain's records."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was added."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
      "description": "When the domain was last changed."
    }
  },
  "required": [
    "id",
    "domain",
    "verificationToken",
    "verifiedAt",
    "emailProvider",
    "emailVerifiedAt",
    "records",
    "lastCheckedAt",
    "createdAt",
    "updatedAt"
  ],
  "additionalProperties": false,
  "description": "The domain, with the records the provider asked for."
}

#Domains

GET /domains

Query parameters

POST /domains

Body parameters

GET /domains/{id}

Path parameters

DELETE /domains/{id}

Path parameters

POST /domains/{id}/verify

Path parameters

POST /domains/{id}/email

Path parameters

Domains

GET `/domains`

POST `/domains`

GET `/domains/{id}`

DELETE `/domains/{id}`

POST `/domains/{id}/verify`

POST `/domains/{id}/email`