API Reference

Update a domain

PATCH /domains/:id — toggle open and click tracking.

PATCH/domains/:id

Updates a domain’s settings. Send any subset of the body fields below; omitted fields are left unchanged. Returns a slim acknowledgement with the domain id. Requires a key with full access. See Open and click tracking.

Body

open_trackingbooleanoptional

Enable or disable the open-tracking pixel for mail sent from this domain. Applied whenever enabled; the pixel is served from your tracking_subdomain when one is configured and verified, otherwise from a shared MailBlastr-hosted host.

click_trackingbooleanoptional

Enable or disable link rewriting for click tracking on this domain. Applied whenever enabled; rewritten links pass through your tracking_subdomain when one is configured and verified, otherwise through a shared MailBlastr-hosted host.

tracking_subdomainstringoptional

A custom subdomain for click and open tracking (e.g. links produces a CNAME for links.yourdomain.com). This value can only be changed after it has first been specified, never removed — this preserves links in already-sent email. After changing it, the new DNS record must be verified; until then links use the shared MailBlastr tracking host, and all previously used records remain active and are included in the response.

tlsstringoptional

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.

capabilitiesobjectoptional

Update the domain capabilities. sending is always enabled and cannot be disabled. Set receiving (enabled | disabled) to toggle whether the domain also receives mail; omitting it keeps the current value.

receivingbooleanoptional

A top-level alias for capabilities.receiving. Enabling it adds the Receiving MX record to records; disabling removes it. capabilities.receiving wins when both are sent.

custom_return_pathstringoptional

A new Return-Path (MAIL FROM) subdomain label — this is the only supported way to change it after creation. Must be a valid DNS label (letters, digits and hyphens, starting and ending alphanumeric, 63 characters or less); anything else returns a validation_error. Changing it re-points MAIL FROM and replaces the SPF MX and TXT records, which must then be published at your DNS provider and re-verified.

custom_trackingbooleanoptional

Turn the custom tracking host on or off. Setting tracking_subdomain implies true. Setting false clears tracking_domain, tracking_subdomain and tracking_verified so new sends fall back to the shared MailBlastr tracking host — the historical tracking DNS records are retained so links in already-sent mail keep working.

import { Mailblastr } from 'mailblastr';

const mb = new Mailblastr('mb_xxxxxxxxx');

const { data, error } = await mb.domains.update('d91a7c4e-1f2b-4a8c-9e3d-7b5f0a2c1d6e', {
  "open_tracking": true,
  "click_tracking": true
});
console.log({ data, error });

Response:

{
  "object": "domain",
  "id": "d91a7c4e-1f2b-4a8c-9e3d-7b5f0a2c1d6e"
}

The response is a slim acknowledgement with only object and id. To read the updated domain object, follow up with `GET /domains/:id`.

Errors: not_found if the domain does not exist or is not yours, restricted_api_key if the key lacks full access. See Errors.