Newsletter domains
A newsletter domain is a separate, verified sending identity used only for bulk mail. It is always a subdomain of a domain that you control, never the root. Shipmail does not need to host the root domain or the Reply-To address. A newsletter sent from updates.example.com and a reply typed by hand from you@example.com build their reputations independently.
That split is on purpose. Bulk mail gets unsubscribes and the odd spam complaint however good it is, and providers score those per sending domain. With newsletters on a subdomain, a bad campaign cannot push your invoices and customer replies into spam.
Last updated
How the addresses are derived
You pick a subdomain label when you set the domain up. Every address follows from it, so you know them all before you create anything.
domain_nameis your label plus the root domain. Suggested labels arenews,updates,announce, andhello, though any valid label under the root works. The root domain itself is rejected.from_addressisfrom_local_partat the newsletter domain. The local part defaults toupdates.mail_from_domainis alwaysmail.prefixed onto the newsletter domain. It carries the bounce path, which is why it needs its own MX and SPF records.reply_to_addressis any monitored email address. It can use a mailbox provider outside Shipmail, so a reader who replies reaches your team.
The MAIL FROM domain is configured to reject on failure rather than fall back to the relay's shared default. If its DNS breaks, sending stops instead of quietly continuing under a weaker identity.
Verification statuses
The top-level status summarizes the domain. The four record fields tell you which DNS entry is holding it back.
pendingmeans the domain exists and its DNS records are not published or not yet observed.verifyingmeans the records were found and verification is waiting on propagation and provider confirmation.verifiedmeans the domain is ready to send. Only domains in this state can be used for a newsletter.failedmeans verification did not complete. The individual record statuses below name the record that failed, and the dashboard shows the underlying provider error.disabledmeans the domain is turned off. It will not send until you re-enable it.
dkim_status, spf_status, mail_from_status, and dmarc_status are each pending, verified, or failed. A domain that sits in verifying for more than an hour almost always has one record still pending, and that field names the record to fix.
List newsletter domains
/v1/newsletter-domainsScope: newsletters:read. Supports cursor and limit pagination.
{
"data": [
{
"object": "newsletter_domain",
"id": "nwsdom_abc123",
"root_domain_name": "example.com",
"domain_name": "updates.example.com",
"from_local_part": "updates",
"from_address": "updates@updates.example.com",
"mail_from_domain": "mail.updates.example.com",
"reply_to_address": "hello@example.com",
"status": "verified",
"dkim_status": "verified",
"mail_from_status": "verified",
"spf_status": "verified",
"dmarc_status": "verified",
"verified_at": "2026-07-04T12:00:00.000Z",
"dns_records": [
{
"key": "mail_from_mx",
"type": "MX",
"host": "mail.updates.example.com",
"value": "feedback-smtp.eu-west-1.amazonses.com",
"priority": 10,
"ttl": 300,
"description": "Routes bounce notifications for newsletters."
}
],
"created_at": "2026-07-04T12:00:00.000Z",
"updated_at": "2026-07-04T12:00:00.000Z"
}
],
"pagination": {
"next_cursor": null,
"has_more": false,
"limit": 25
}
}Get a newsletter domain
/v1/newsletter-domains/:idscope newsletters:readReturns one domain in the same shape as the list items above, so you can poll a single domain while its records verify. It answers 404 for an ID outside your organization, a domain still being set up, and for a key limited to domains or mailboxes, which cannot see newsletter domains.
Use with sender identities
A newsletter draft selects a reusable sender identity, not a domain directly. Each sender identity points to one newsletter domain and also carries the From name and footer business details for a brand. See the sender identities reference to list them and create a draft.
Set up a newsletter domain
/v1/newsletter-domainsscope newsletters:write{
"root_domain": "example.com",
"subdomain": "updates",
"from_local_part": "updates",
"reply_to_address": "hello@example.com",
"reply_to_name": "Example"
}Only root_domain and reply_to_address are required. subdomain is a label (default news) or the full name. The response is the domain, status pending, with dns_records: the DKIM, MAIL FROM MX, MAIL FROM SPF and DMARC records to publish at your DNS host. Each has a type, the full host, a value and, for MX, a priority. If a request stops part way, sending it again resumes the setup.
Verify and delete
POST /v1/newsletter-domains/:id/verify
DELETE /v1/newsletter-domains/:idScope: newsletters:write. Verify checks the published records now and returns the domain with each status. DNS can take minutes to propagate, so call it again while a record is pending. Shipmail also checks pending domains on its own. Delete answers 204, or 409 while a draft or active newsletter uses the domain.
These three endpoints follow the dashboard's rules: the API key's person must be an Owner or Administrator with access to every mailbox, the plan's newsletter domain limit applies, and a key limited to mailboxes, domains or audiences is refused. Changing the subdomain later means verifying a new identity and starting its reputation over, so pick the label with care.