Subscriptions & Consent

How subscription types, subtype consent, campaigns, and double opt-in work in ArtaMail.

Concepts

Three levels — do not mix them up:

One type or several? (within one account)

Multiple brands → separate accounts, not extra subscription types. Types are for consent categories inside one product.

Example: three preference sections

Suppose your app shows three blocks — Account activity, System & reports, and Community & roadmap — each with one or more toggles.

Option A — one type (common with custom UI)

Type: email-preferences
├── account-activity      (operational)  "Real-time work updates"
├── system-reports        (operational)  "Critical platform updates"
└── community-roadmap     (marketing)    "Optional events & insights"
→ One GET /api/u/{token}/data returns all subtypes
→ Your UI renders three sections; POST preferences uses subtype slugs
→ Emails use {{unsubscribe_url}} (global link)

Option B — three types (section-specific unsubscribe in emails)

Type: account-activity
└── work-progress         (operational)
Type: system-reports
└── platform-alerts       (operational)
Type: community-roadmap
└── events-insights       (marketing)   ← bind campaigns here
→ Community campaigns use {{unsubscribe_community_roadmap}}
→ One-click unsub on that link does not touch account-activity subtypes

Configure types in Dashboard → Subscription Types. See Custom Preference URLs for building your own preference page.

Subtype details

Opt-in via API

Grant subtype consent when creating or updating a contact:

const res = await fetch('https://artamail.artatol.net/api/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer am_live_sk_xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: '[email protected]',
    name: 'Jane',
    locale: 'en',
    opt_in_subtype_slugs: ['weekly-digest'],
  }),
});
const contact = await res.json();
// contact.pending_confirmation — true when org double opt-in applies
// contact.confirm_url — send this in your consent-confirm email

Double opt-in (DOI)

Enable Require double opt-in in Dashboard → Settings → Subscription consent. When on, API opt-ins set subscribed=true but leave confirmed_at null until the contact clicks confirm_url.

Your responsibilities

1. Create a transactional template with slug consent-confirm (preset available in dashboard).
2. Include {{confirm_url}}, {{name}}, {{brand}}, {{legal_entity}}, and optionally {{legal_address}} / {{legal_details}} in the template (use the consent-confirm preset as a starting point).
3. After POST /api/v1/contacts, send the confirm email yourself — ArtaMail does not auto-queue it.
4. Contact clicks the link → GET /api/confirm/[token] sets confirmed_at. Optionally redirects using the success URL on the confirm template.

Configure the redirect URL on each consent template in the dashboard. Pass confirm_template on signup to bind token and email to the right app. See the Double Opt-In Redirect guide.

import { ArtaMail } from '@artatol/artamail-sdk';
const artamail = new ArtaMail({ apiKey: process.env.ARTAMAIL_API_KEY! });
// Option A: two steps
const contact = await artamail.upsertContact({
  email: '[email protected]',
  optInSubtypeSlugs: ['weekly-digest'],
});
if (contact.confirmUrl) {
  await artamail.sendConsentConfirmEmail({
    to: contact.email,
    confirmUrl: contact.confirmUrl,
    name: contact.name,
    // brand, legal_entity auto-injected from account Settings
  });
}
// Option B: one call
await artamail.optInContact({
  email: '[email protected]',
  optInSubtypeSlugs: ['weekly-digest'],
  sendConfirmEmail: true,
});
// Skip DOI (import, admin override)
await artamail.upsertContact({
  email: '[email protected]',
  optInSubtypeSlugs: ['weekly-digest'],
  doubleOptIn: false,
});

In-app settings (API key)

When users manage subscriptions inside your authenticated app (not via an email link), use the API key endpoints — no HMAC token required. Your server must verify the email belongs to the logged-in user before calling ArtaMail.

import { getArtaMail } from '@artatol/artamail-nextjs/server';
const artamail = getArtaMail();
// Load toggles
const prefs = await artamail.getContactSubscriptionPreferences(user.email);
const types = await artamail.listSubscriptionTypes();
// Save toggles (immediate confirm — no double opt-in on this endpoint)
await artamail.updateContactSubscriptionPreferences(user.email, {
  preferences: { 'newsletter/weekly-digest': true },
});
// Master marketing switch
await artamail.updateContact(user.email, { subscribed: false });
// Account deletion — permanent; PII and subscriptions removed
await artamail.deleteContact(user.email);

Campaigns

Marketing campaigns must bind at least one marketing subtype when your org has marketing subtypes configured. Sends filter recipients with is_contact_opted_in (subscribed + confirmed).

Multiple products

The default setup is one ArtaMail account per brand — isolated contacts, domains, API keys, and a preferences_url_templateper account. Set brand, legal entity, legal address, and legal details in Settings → Brand & compliance.

Advanced: shared contacts across apps in one account

Multilingual preference pages

User-facing preference and unsubscribe pages resolve text from contacts.locale, with fallback to your account's supported locales (Settings → Contact locales) and then English.

What lives where

Configure per-locale copy in Settings → Preference page. Subtype labels use locale tabs on Subscription Types. The API exposes subtype i18n via Subscription Types API; Preferences Data API returns resolved strings for custom UIs.

Custom preference URLs

Optionally set a preferences_url_template in dashboard settings (e.g. https://prefs.example.com/manage?token={{token}}). When set, ArtaMail substitutes the signed token at send time for {{unsubscribe_url}} and List-Unsubscribe headers for all marketing sends in the org. Use {{unsubscribe_token}} when you build per-brand URLs yourself in template HTML instead.