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 multiple workspaces, but sending is enabled for the workspace whose DKIM key is published. To move sending, add the domain in the destination workspace and publish its DNS records. The next verification check updates sending readiness; existing mail remains in its original workspace. Duplicate apex or wildcard identities within one workspace 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.
POST
/domainsAuthorization
AuthorizationBearer token (API key) · headerrequiredPass an AI Inbx API key as a Bearer token.
Request body
requiredapplication/jsonnamestringrequiredA 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
regionstringAllowed:
eu-central-1us-east-1space_idstringWhich space a created resource goes in. Omitted, the workspace itself.
matches ^[a-z]+_[0-9a-f]{32}$
Responses
201The domain was created.
idstringrequiredmatches ^[a-z]+_[0-9a-f]{32}$
namestringrequiredregionstringrequiredAllowed:
eu-central-1us-east-1space_idstring | anyrequiredWhich space a resource is in. Null is the workspace itself — what every resource of a workspace that has no spaces says.
Show propertiesHide properties
Any of:
string
stringany
anyparent_idstring | anyrequiredThe wildcard this subdomain is filed under, when it is one.
Show propertiesHide properties
Any of:
string
stringany
anyprovidedbooleanrequiredWhether 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> | anyrequiredShow propertiesHide properties
Any of:
string<date-time>
string<date-time>any
anycreated_atstring<date-time>requiredmatches ^(?:(?:\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))$
trackingobjectrequiredShow propertiesHide properties
opensbooleanrequiredclicksbooleanrequiredrecordsobject[]Show propertiesHide properties
Array of
objectpurposestringrequiredAllowed:
SPFDKIMDMARCRETURN_PATHINBOUNDtypestringrequiredAllowed:
MXTXTCNAMEnamestringrequiredvaluestringrequiredttlintegerrequiredmin 0 · max 9007199254740991
statestringrequiredAllowed:
pendingverifiedmissinglast_checked_atstring<date-time> | anyrequiredShow propertiesHide properties
Any of:
string<date-time>
string<date-time>any
any400The request is invalid.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired401The API key is missing or invalid.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired403The API key does not have the required scope.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired404The requested resource does not exist.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired409The request conflicts with the resource's current state.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired413The request body or attachments are too large.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired415The request body is not JSON.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired422The request body failed validation.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired429The organisation's request budget is spent (`too_many_requests`), or an upstream mail provider is throttling (`rate_limited`).
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired500An internal error occurred.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired502An upstream mail provider failed.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired503The service is temporarily unavailable.
typestringrequiredtitlestringrequiredstatusintegerrequiredmin -9007199254740991 · max 9007199254740991
detailstringrequiredcodestringrequiredrequest_idstringrequiredissuesobject[]Show propertiesHide properties
Array of
objectpathstringrequiredmessagestringrequired