API Reference

Subscription Types API

Read subscription types, subtypes, and contact consent state. Configure types in the dashboard.

Dashboard configuration

Create and edit subscription types in Dashboard → Subscription Types. The API is read-only for types; consent is granted via contact opt-in or the preference center. Not sure how many types you need? See the Subscriptions guide.

GET/api/v1/subscription-types

List all subscription types and subtypes for your organization.

Terminal

curl https://artamail.artatol.net/api/v1/subscription-types \
  -H "Authorization: Bearer am_live_sk_xxx"

Response

json

{
  "types": [
    {
      "id": "uuid",
      "slug": "newsletter",
      "label": "Newsletter",
      "description": null,
      "is_active": true,
      "subtypes": [
        {
          "id": "uuid",
          "slug": "weekly-digest",
          "label": "Weekly digest",
          "description": "Main newsletter",
          "label_i18n": { "en": "Weekly digest", "cs": "Týdenní přehled" },
          "description_i18n": { "en": "Main newsletter", "cs": "Hlavní newsletter" },
          "channel": "marketing",
          "is_active": true
        }
      ]
    }
  ],
  "test_mode": false
}

Localized preference copy

Field	Scope	Description
`label_i18n`	Subtype	Locale-keyed toggle label shown on the preference page
`description_i18n`	Subtype	Locale-keyed optional description under each toggle
`label`	Subtype	Denormalized primary-locale label (synced on save). Prefer resolving from `label_i18n` for display.

Page copy

Preference page strings (title, buttons, footer, etc.) are org-wide in Settings → Preference page (preference_page.global_copy). See Preferences Data API.

Subtype channels

Channel	Description
`marketing`	Campaign sends; requires opt-in + confirmation for DOI orgs
`operational`	Product updates; consent required for transactional API with subtype_slug
`transactional`	Receipts, auth emails; not managed via preference toggles

GET/api/v1/subscription-types/:slug

Get a single subscription type by slug.

Terminal

curl https://artamail.artatol.net/api/v1/subscription-types/newsletter \
  -H "Authorization: Bearer am_live_sk_xxx"

GET/api/v1/contacts/:email/subscription-preferences

Read a contact's subtype consent rows including provenance and confirmation state. Update via PATCH /api/v1/contacts/:email/subscription-preferences — see Contacts API.

json

{
  "email": "[email protected]",
  "preferences": [
    {
      "type_slug": "newsletter",
      "type_label": "Newsletter",
      "subtype_slug": "weekly-digest",
      "subtype_label": "Weekly digest",
      "subtype_channel": "marketing",
      "subscribed": true,
      "consented_at": "2024-01-15T10:30:00Z",
      "consent_source": "api",
      "consent_method": "api",
      "confirmed_at": "2024-01-15T10:35:00Z"
    }
  ],
  "test_mode": false
}

Confirm endpoint (browser)

Double opt-in links point to GET /api/confirm/[token]. This is a public URL (HMAC-signed token), not an API-key endpoint. Returns JSON on success.

Full consent & DOI guide →