Skip to content
Sign inGet startedDashboard

Newsletters APISender identities

Newsletter sender identities

A sender identity groups the public details for one brand: its From name, sending address, footer business name, postal address, and optional footer text. A workspace can create several identities, including several on the same sending domain, then choose one per newsletter.

Last updated

From name and business name

from_name is what recipients see in the From field in their email client. business_name is the organization or brand shown in the newsletter footer. They can match. They are separate so the inbox can say "Acme Product Team" while the legal footer says "Acme Holdings Ltd."

List sender identities

GET/v1/newsletter-sender-identities

Scope: newsletters:read. Supports cursor and limit pagination.

{
  "data": [
    {
      "object": "newsletter_sender_identity",
      "id": "nwsid_abc123",
      "newsletter_domain_id": "nwsdom_abc123",
      "from_name": "Acme Product Team",
      "from_address": "updates@news.example.com",
      "business_name": "Acme Holdings Ltd.",
      "postal_address": "1 Market Street, London",
      "footer_text": "Product news for Acme customers.",
      "domain_status": "verified",
      "is_default": true,
      "created_at": "2026-07-29T12:00:00.000Z",
      "updated_at": "2026-07-29T12:00:00.000Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false,
    "limit": 25
  }
}

Use with newsletters

Select an identity whose domain_status is verified. The default is handy in interactive tools. In an integration, store the identity ID you want, so a later change of default cannot switch brands.

const identities = await shipmail.newsletters.senderIdentities.list({
  limit: 25,
});

const sender = identities.data.find(
  (identity) => identity.is_default && identity.domain_status === "verified",
);
if (!sender) {
  throw new Error("No verified newsletter sender identity.");
}

const newsletter = await shipmail.newsletters.create({
  audience_id: "aud_abc123",
  sender_identity_id: sender.id,
  name: "July changelog",
  subject: "What shipped in July",
  body_html: "<h1>July updates</h1><p>...</p>",
});

Create and edit identities

The endpoint is read-only. Owners create, edit, choose the default, and remove unused identities under Newsletters → Settings. An identity in use by a newsletter cannot be removed. Sending domains and Reply-To addresses are managed separately.