Skip to content
AI Inbx
Esc
↑↓navigate↵open⌘Jpreview

Create a domain

Registers a sending domain and returns the DNS records to publish: SPF, DKIM, DMARC, a return path, and an MX record for receiving. region selects the regional mail infrastructure for this domain and cannot be changed afterwards.

A wildcard — *.acme.dev — is verified once and covers every subdomain: the MX record goes at *.acme.dev, the rest at acme.dev, and the apex keeps whatever mail setup it has. A name one label under a wildcard of yours — hi.acme.dev under *.acme.dev — is created as a subdomain of it: no records, verified as soon as the wildcard is, in whatever space_id you give it. That is how a platform hands each customer an address of their own without touching DNS again.

A domain name can be connected in several spaces and workspaces, but sending and receiving are enabled for the one whose DKIM key is published. To move them, add the domain where it should go and publish its DNS records. The next verification check moves them; existing mail stays where it was. Duplicate apex or wildcard identities within one space fail with domain_taken.

Every workspace already has one domain it did not add: <slug>.aiinbx.app, listed with provided: true. It is verified through our zone, has no records and cannot be deleted; a name under aiinbx.app cannot be added by hand and fails with reserved_domain.

A domain of its own counts against the plan’s custom domains — a subdomain under a wildcard and the provided domain do not. With none left the request fails with 402 allowance_reached, and a workspace with no plan with 402 plan_required.

track_opens and track_clicks set the domain’s tracking; what they leave out starts as the workspace’s tracking defaults in the console say — off unless they are set there — or, on a subdomain, as its wildcard’s. Change either afterwards with PATCH /domains/{domain_id}.

POST/domains
Authorization
AuthorizationBearer token (API key) · headerrequired

Pass an AI Inbx API key as a Bearer token.

Header parameters
AIInbx-Workspacestring

Workspace id from GET /workspaces, for an OAuth token that reaches several.

min length 1
Request body
requiredapplication/json
namestringrequired

A domain, a wildcard (*.acme.dev), or one label under a wildcard you own (hi.acme.dev) — the last is created as a subdomain with no records.

min length 3 · max length 253
regionstring

The region the domain's mail is handled in.

Allowed:eu-central-1us-east-1
space_idstring

Which space a created resource goes in. Omitted, the workspace itself.

matches ^[a-z]+_[0-9a-f]{32}$
track_opensboolean

Whether opens are tracked on mail sent from the domain.

track_clicksboolean

Whether links are rewritten to track clicks on mail sent from the domain.

Responses
201

The domain was created.

idstringrequired
matches ^[a-z]+_[0-9a-f]{32}$
namestringrequired
regionstringrequired

Where the domain's mail is handled today. A domain carried over from the previous aiinbx reports us-east-1 until its records verify here, then the region chosen for it.

Allowed:eu-central-1us-east-1
space_idstring | nullrequired

Which space a resource is in. Null is the workspace itself — what every resource of a workspace that has no spaces says.

Show properties
Any of:
string
string
null
null
parent_idstring | nullrequired

The wildcard this subdomain is filed under, when it is one.

Show properties
Any of:
string
string
null
null
providedbooleanrequired

Whether this is the domain the workspace was given — <slug>.aiinbx.app. Verified through our own zone, so it has no records and cannot be deleted.

verified_atstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
created_atstring<date-time>required
matches ^(?:(?:\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))$
trackingobjectrequired
Show properties
opensbooleanrequired
clicksbooleanrequired
recordsobject[]
Show properties
Array of object
purposestringrequired
Allowed:SPFDKIMDMARCRETURN_PATHINBOUND
typestringrequired
Allowed:MXTXTCNAME
namestringrequired
valuestringrequired
ttlintegerrequired
min 0 · max 9007199254740991
statestringrequired
Allowed:pendingverifiedmissing
last_checked_atstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
400

The request is invalid.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
401

The API key is missing or invalid.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
402

The workspace has no plan (plan_required), or its plan's allowance is used up (allowance_reached).

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
403

The API key or token does not have the required scope, or the token is connected as an inbox and the operation is not one an inbox may use.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
404

The requested resource does not exist.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
409

The request conflicts with the resource's current state.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
413

The request body or attachments are too large.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
415

The request body is not JSON.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
422

The request body failed validation.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
429

The organisation's request budget is spent (too_many_requests), or an upstream mail provider is throttling (rate_limited).

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
500

An internal error occurred.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
502

An upstream mail provider failed.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
503

The service is temporarily unavailable.

typestringrequired
titlestringrequired
statusintegerrequired
min -9007199254740991 · max 9007199254740991
detailstringrequired
codestringrequired
request_idstringrequired
issuesobject[]
Show properties
Array of object
pathstringrequired
messagestringrequired
Request
import AIInbx from "aiinbx"

const aiinbx = new AIInbx()

const response = await aiinbx.domains.create({
  name: "mail.example.com",
  region: "eu-central-1",
})
Response
{
  "id": "string",
  "name": "string",
  "region": "eu-central-1",
  "space_id": "string",
  "parent_id": "string",
  "provided": true,
  "verified_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "records": [
    {
      "purpose": "SPF",
      "type": "MX",
      "name": "string",
      "value": "string",
      "ttl": 0,
      "state": "pending",
      "last_checked_at": "2019-08-24T14:15:22Z"
    }
  ]
}