Brands and shared contacts

​

Goal

​

Prerequisites

• Keep Mail credentials on your backend. API examples use https://api.stackshift.cloud/v1 unless a public /api/v1 route is stated.

​

Workflow

​

Brand endpoints and fields

• GET/POST /mail/brands lists or creates brands; GET/PUT /mail/brands/{id} reads or updates one; POST /mail/brands/{id}/archive archives it. Create returns HTTP 201; reads, updates and archive return HTTP 200.
• name is required, trimmed and limited to 120 bytes. Optional fields are logoUrl, sendingDomainId (UUID or null), defaultFrom, replyTo, postalAddress (up to 1,000 bytes), website, supportEmail and editableFields (up to 50 unique names).
• defaultFrom, replyTo and supportEmail must parse as email addresses without CR/LF and fit 320 bytes. website must be HTTPS without embedded credentials and fit 2,048 bytes.
• Editable names match ^[a-z][a-z0-9_]{0,63}$. These are the custom fields subscribers may edit; the shared name is also editable.
• Responses include id, workspaceId, mode, status (active or archived), revision, createdAt and updatedAt. PUT requires a positive current revision and the full desired brand fields, including name. Reload on a conflict instead of overwriting another edit. Unknown request fields are rejected.

​

Create a brand before its audience

import { StackShift } from '@stackshift-cloud/sdk'
const client = new StackShift({ apiKey: process.env.STACKSHIFT_MAIL_TEST_KEY! })
const brand = await client.mail.brands.create({
  name: 'Product news', defaultFrom: 'Product <hello@example.com>',
  replyTo: 'support@example.com', website: 'https://example.com',
  postalAddress: 'Your actual mailing address', supportEmail: 'support@example.com',
  editableFields: ['company', 'interests'],
})
const audience = await client.mail.audiences.create({
  brandId: brand.id, name: 'Release announcements', description: 'Product updates',
})
const updated = await client.mail.brands.update(brand.id, {
  name: brand.name, defaultFrom: brand.defaultFrom, replyTo: brand.replyTo,
  postalAddress: brand.postalAddress, website: brand.website,
  supportEmail: brand.supportEmail, editableFields: ['company'], revision: brand.revision,
})

​

Logo validation and sending domains

• Choose a current-version, public, ready, clean PNG, JPEG or GIF from the workspace’s default Assets space. The logo must be at most 5 MiB and use the configured CDN /assets/{assetId}/versions/{versionId} URL without a query or fragment. External image URLs, signed/private URLs, SVGs and arbitrary HTML/CSS are not accepted.
• Domains remain workspace-owned and reusable by brands. A sendingDomainId must belong to the workspace and environment. When it is set, defaultFrom must use that domain. Brand choice never bypasses live sender verification or a credential’s sender-domain restrictions.
• A brand is required for each audience; campaign, form, segment and automation ownership follows the audience. Cross-brand or cross-environment resource combinations are rejected. There is no default brand or audience fallback.

​

Shared profiles and independent memberships

• A contact profile is identified by brand plus normalized email within the workspace and environment. Name and custom attributes are shared across that brand’s lists; another brand has an independent profile.
• Each audience membership independently stores consent evidence, pending/confirmed state and subscription status. Updating a profile does not grant consent to another list.
• Preference pages show only existing memberships within the link’s brand and approved fields. The email address is not editable there. New unsubscribe-all actions apply within that brand; old workspace-scoped links retain their original scope. Workspace opt-outs and hard-bounce/complaint protections still apply.
• Archived brands retain history and usable unsubscribe/preference pages, but cannot start new sends. Archive is not deletion. There is no unarchive endpoint in this implementation.

​

Compatibility and migration

​

Python and Go SDK equivalents

import os
from stackshift import StackShift
client = StackShift(api_key=os.environ["STACKSHIFT_MAIL_TEST_KEY"])
brand = client.mail.brands.create(name="Product", editable_fields=["company"])
audience = client.mail.audiences.create(brand_id=brand["id"], name="Product news")
print(audience["id"])

package example

import (
    "context"
    stackshift "github.com/stackshiftCloud/assets-go"
)

func createAudience(ctx context.Context, client *stackshift.Client) error {
    brand, err := client.Mail.Brands.Create(ctx, stackshift.MailBrandFields{Name: "Product"})
    if err != nil { return err }
    _, err = client.Mail.Audiences.Create(ctx, stackshift.MailAudienceCreateRequest{
        BrandID: brand.ID, Name: "Product news",
    })
    return err
}

​

Existing CLI audience command

stackshift mail audience-create --data '{"brandId":"BRAND_UUID","name":"Product news"}'

​

Expected result

​

Related guides