API Reference

Create a domain

POST /domains — add a sending domain and get its SPF and DKIM records.

POST/domains

Adds a domain, provisions its sending identity (DKIM + custom MAIL FROM), and returns the domain object — including the records array of DNS entries to publish. The new domain starts with status not_started. Requires a key with full access.

Body

namestringrequired

The bare domain to add, e.g. yourdomain.com. Lower-cased and validated as a domain.

regionstringoptional

Optional. The region the sending identity is created in. Available values: us-east-1 | ap-south-1 (default us-east-1). eu-west-1, sa-east-1 and ap-northeast-1 are coming soon and return a validation_error (422) today; an unrecognised value falls back to the default. See Choosing a region.

custom_return_pathstringoptional

Optional. The subdomain used for the Return-Path (MAIL FROM) address, which carries SPF authentication, DMARC alignment, and bounce handling. Defaults to send (i.e. send.yourdomain.com). Avoid values that could undermine credibility (e.g. testing), as they may be exposed to recipients. See Custom return path.

open_trackingbooleanoptional

Optional. Track the open rate of each email. Applied whenever this flag is on; if a tracking_subdomain is configured and verified the open pixel is served from it, otherwise from a shared MailBlastr-hosted host. Defaults to false. See Open and click tracking.

click_trackingbooleanoptional

Optional. Track clicks within the body of each HTML email. Applied whenever this flag is on; if a tracking_subdomain is configured and verified the rewritten links are served from it, otherwise from a shared MailBlastr-hosted host. Defaults to true.

tracking_subdomainstringoptional

Optional. A custom subdomain for click and open tracking. For example, setting links on example.com produces a CNAME record for links.example.com. Avoid values with a negative connotation (e.g. tracking).

tlsstringoptional

Optional. The domain’s TLS preference. opportunistic (default) encrypts the connection when the receiving server supports TLS and otherwise sends unencrypted; enforced records a preference that delivery should require TLS. Defaults to opportunistic. See Enforced TLS.

capabilitiesobjectoptional

Optional. Configure the domain capabilities. sending is always enabled. Contains receiving (enabled | disabled, default disabled) to also receive mail for the domain.

import { Mailblastr } from 'mailblastr';

const mb = new Mailblastr('mb_xxxxxxxxx');

const { data, error } = await mb.domains.create({
  "name": "yourdomain.com"
});
console.log({ data, error });

Response — the domain object. The records array lists every DNS entry to publish (the DKIM TXT, the SPF MX and TXT on the send. subdomain, and — when a tracking_subdomain is configured — a Tracking CNAME):

{
  "object": "domain",
  "id": "d91a7c4e-1f2b-4a8c-9e3d-7b5f0a2c1d6e",
  "name": "yourdomain.com",
  "zone": "yourdomain.com",
  "status": "not_started",
  "region": "us-east-1",
  "created_at": "2026-06-23T12:00:00.000Z",
  "custom_return_path": "send",
  "open_tracking": false,
  "click_tracking": true,
  "tracking_subdomain": null,
  "tls": "opportunistic",
  "capabilities": {
    "sending": "enabled",
    "receiving": "disabled"
  },
  "tracking_domain": null,
  "tracking_verified": false,
  "aws_last_checked_at": null,
  "aws_check_error": null,
  "records": [
    {
      "record": "DKIM",
      "name": "mailblastr._domainkey.yourdomain.com",
      "type": "TXT",
      "ttl": "Auto",
      "status": "not_started",
      "value": "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."
    },
    {
      "record": "SPF",
      "name": "send.yourdomain.com",
      "type": "MX",
      "ttl": "Auto",
      "status": "not_started",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "priority": 10
    },
    {
      "record": "SPF",
      "name": "send.yourdomain.com",
      "type": "TXT",
      "ttl": "Auto",
      "status": "not_started",
      "value": "v=spf1 include:amazonses.com ~all"
    }
  ]
}

The Tracking CNAME is only returned when a tracking_subdomain is set. The DKIM and SPF records are always returned. DMARC is not generated — publish it yourself, see DNS records.

zone is the managing DNS zone that each record name is relative to — it is the domain itself unless the domain is delegated to a parent zone. aws_last_checked_at and aws_check_error report the last provider DNS poll: the ISO timestamp of the most recent check, and the error it returned (or null when the check succeeded or has not run yet).

Errors: missing_required_field if name is absent, validation_error if name is not a valid domain, you already have that domain, or region is not an available region, domain_conflict (409) if the domain — or a parent/subdomain of it — is already verified by a different account (use `POST /domains/claim`), restricted_api_key if the key lacks full access, and plan_limit_reached (402) when the account is already at its plan's domain limit — the body carries kind: "domains" with used, limit, requested and next_plan. See Errors.