API Reference

Create a domain

POST /domains — add a sending domain and get its SPF, DKIM, and DMARC 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, for compatibility. The region where emails will be sent from. Possible values: us-east-1 | eu-west-1 | sa-east-1 | ap-northeast-1 (default us-east-1). The domain is always pinned to MailBlastr’s configured region regardless of this value. 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 false.

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, the DMARC TXT, and — when a tracking_subdomain is configured — a Tracking CNAME):

{
  "object": "domain",
  "id": "d91a7c4e-1f2b-4a8c-9e3d-7b5f0a2c1d6e",
  "name": "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": false,
  "tracking_subdomain": null,
  "tls": "opportunistic",
  "capabilities": {
    "sending": "enabled",
    "receiving": "disabled"
  },
  "tracking_domain": null,
  "tracking_verified": false,
  "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"
    },
    {
      "record": "DMARC",
      "name": "_dmarc.yourdomain.com",
      "type": "TXT",
      "ttl": "Auto",
      "status": "not_started",
      "value": "v=DMARC1; p=none;"
    }
  ]
}

The Tracking CNAME is only returned when a tracking_subdomain is set. The DKIM, SPF, and DMARC records are always returned.

Errors: missing_required_field if name is absent, validation_error if name is not a valid domain or the domain already exists, and invalid_access if the key lacks full access. See Errors.