Advanced

Shared Contacts Across Apps (One Account)

Use this pattern only when you explicitly want one contact database across multiple apps. For isolated contacts, domains, and custom UX per product, use one account per brand instead.

Default recommendation

Most teams should use a separate ArtaMail account per brand. This guide covers the niche case where contacts, subscription types, and campaigns are intentionally shared.

One brand & legal identity per account

A single ArtaMail account has one brand name and one set of legal/compliance fields ( legal entity, address, details) in Settings. You cannot assign different legal entities per app inside one account — use one account per product when brands need separate compliance identity.

When this pattern fits

One ArtaMail account can power several branded apps (e.g. App A and App B). Contacts, subscription types, and campaigns are shared — but you can still send users back to the right app and brand preference links per product.

Two separate mechanisms

Post-signup redirect and marketing unsubscribe links are configured independently. You do not need an org-wide custom preference URL to run a multi-brand double opt-in flow.

Flow	Org setting required?	Per-brand option
Double opt-in — where the user lands after clicking `confirm_url`	No org-wide URL	One consent template per app with its own Success redirect URL. Pass `confirm_template` on signup.
Marketing unsubscribe / preferences — links in campaigns and `List-Unsubscribe` headers	Optional `preferences_url_template` in Settings	Org template applies to all brands. For different domains per app, use bare token variables in each marketing template (see below).

Recommended setup (two apps)

Shared in the org: subscription types, subtypes, contact lists, and (optionally) a single preferences_url_template if every brand should use the same preference domain.
Per app — DOI: duplicate the consent-confirm preset → consent-confirm-app-a, set Success redirect URL to https://app-a.example.com/welcome. Repeat for App B.
Per app — signup: pass the matching template slug when opting in.
Per app — marketing emails: either use default ArtaMail links, org-wide custom URLs, or per-template branded links with token variables.

multi-brand-signup.ts

// App A signup
await artamail.upsertContact({
  email: '[email protected]',
  optInSubtypeSlugs: ['weekly-digest'],
  confirmTemplate: 'consent-confirm-app-a',
});
// App B signup — same org, different confirm template + redirect
await artamail.upsertContact({
  email: '[email protected]',
  optInSubtypeSlugs: ['weekly-digest'],
  confirmTemplate: 'consent-confirm-app-b',
});

Optional redirect host allowlist

Settings → Subscription consent → DOI redirect hosts can list every brand domain (app-a.example.com, app-b.example.com). When empty, any HTTPS redirect URL on a template is accepted.

Marketing preference links — three choices

Approach	Setup	Best for
Default ArtaMail URLs	Nothing to configure	Fastest start. Links point to `artamail…/api/u/{token}` in body and `List-Unsubscribe`.
Org-wide custom domain	Settings → `preferences_url_template` with `{{token}}`	One white-label domain for all brands (e.g. shared `prefs.company.com` proxy).
Per-brand links in templates	Build URLs in HTML with `{{unsubscribe_token}}` or `{{unsubscribe_token_<slug>}}`	Different domains per app in the email body — no org preference URL required. Your app proxies GET/POST to ArtaMail.

List-Unsubscribe is org-wide

The List-Unsubscribe header always uses the org preferences_url_template or the ArtaMail default — not per-template body URLs. For Gmail one-click on a brand-specific domain, either set one shared org template (proxy routes by token) or accept the ArtaMail URL in the header while branding only in-email links.

Example per-brand body link in App A's campaign template:

html

<a href="https://app-a.example.com/preferences?token={{unsubscribe_token}}">
  Manage email preferences
</a>

Quick reference

What	Shared org-wide	Per brand / per template
Contacts & consent rows	Yes	—
DOI success redirect	—	`confirm_success_redirect_url` on consent template
Which confirm email to send	—	`confirm_template` on API signup
`{{unsubscribe_url}}`	Org template or ArtaMail default	Not per brand
Branded preference link in email body	—	`{{unsubscribe_token}}` + your URL in template HTML
`List-Unsubscribe` header URL	Org template or ArtaMail default	Not per brand