API Reference

Preferences Data API

Load subscription and identity data for a custom preference UI. No API key required — the signed token in the URL is the credential. All user-facing strings are resolved for the contact's locale.

Custom preference URLs

Used when you host preference links on your domain. See the Custom Preference URLs guide for GET/POST proxy setup. Save consent with POST /api/u/{token}/preferences.

GET/api/u/{token}/data

Returns brand, legal entity, contact email, resolved page copy, and subscription subtypes for the token scope. Tokens are HMAC-signed and issued at send time (same token as {{unsubscribe_token}}).

Locale resolution

The response includes locale (from contacts.locale) and a resolved copy object with all page strings already picked for that locale. Subtype label / description fields are also localized. Fallback order: exact locale → language subtag → org supported locales → English.

Example Request

Terminal

curl https://artamail.artatol.net/api/u/SIGNED_TOKEN/data

Response

json

{
  "orgId": "550e8400-e29b-41d4-a716-446655440000",
  "orgName": "SuperWidget",
  "legalEntityName": "Acme Holdings s.r.o.",
  "email": "[email protected]",
  "locale": "cs",
  "copy": {
    "title": "Předvolby newsletteru",
    "subtitle": "Vyberte, jaké e-maily chcete dostávat od SuperWidget.",
    "footer": "Powered by ArtaMail",
    "button_save": "Uložit předvolby",
    "button_unsubscribe": "Odhlásit se ze všeho",
    "button_confirm_unsubscribe": "Potvrdit odhlášení",
    "empty_confirm_message": "Chystáte se odhlásit z e-mailů SuperWidget.",
    "success_title": "Předvolby uloženy",
    "success_message": "Vaše nastavení bylo aktualizováno.",
    "success_button_text": "",
    "success_button_href": "",
    "button_update_again": "Upravit předvolby znovu",
    "success_changes_subscribed": "Budete dostávat: {{list}}",
    "success_changes_unsubscribed": "Nebudete dostávat: {{list}}",
    "transactional_note": "Servisní e-maily (vždy zapnuto)",
    "error_invalid_link": "Neplatný nebo expirovaný odkaz.",
    "error_save_failed": "Uložení se nezdařilo.",
    "type_title": "Předvolby newsletteru"
  },
  "oneClickCopy": {
    "success_title": "Odhlášeno",
    "success_message": "Byli jste odhlášeni z našeho seznamu.",
    "success_transactional_note": "Transakční e-maily mohou být stále odesílány.",
    "success_close_note": "Toto okno můžete zavřít.",
    "error_invalid": "Tento odkaz je neplatný.",
    "error_failed": "Požadavek se nepodařilo zpracovat.",
    "typed_success_message": "Byli jste odhlášeni z e-mailů Předvolby newsletteru."
  },
  "type": {
    "id": "type-uuid",
    "slug": "newsletter",
    "label": "Newsletter",
    "customHtml": null,
    "showUnsubscribeAll": true
  },
  "subtypes": [
    {
      "id": "subtype-uuid-1",
      "slug": "weekly-digest",
      "typeSlug": "newsletter",
      "label": "Týdenní přehled",
      "description": "Hlavní newsletter",
      "channel": "marketing",
      "sortOrder": 0,
      "subscribed": true
    }
  ]
}

Response Fields

Field	Type	Description
`orgId`	string	ArtaMail account ID
`orgName`	string	Brand name (also available as `copy` via {{brand}} in templates)
`legalEntityName`	string	Legal entity for footers; falls back to brand when unset in Settings
`email`	string	Contact email from the token
`locale`	string	Contact locale used to resolve copy and subtype labels (e.g. `cs`)
`copy`	object	Resolved page strings from org `preference_page.global_copy` (Settings → Preference page). Includes optional `success_button_text` / `success_button_href` for a post-save CTA. Hosted UI: `/preferences/{token}`. Same copy for global and typed tokens; use `{{type_title}}` for type-specific wording.
`oneClickCopy`	object	Resolved one-click unsubscribe success/error strings (org settings). Shown after RFC 8058 POST or `?one_click=1` redirect.
`type`	object \| null	Present when token is scoped to one subscription type; includes optional `customHtml` template
`subtypes`	array	Subtypes with localized `label` / `description` and `subscribed` consent state

Custom HTML placeholders

When a type uses custom HTML, ArtaMail substitutes these in addition to building {{subtypes_form}}:

Placeholder	Source
`{{title}}`	`copy.title`
`{{subtitle}}`	`copy.subtitle`
`{{footer}}`	`copy.footer`
`{{button_save}}`	Injected into subtypes form
`{{button_unsubscribe}}`	Unsubscribe-from-all button in subtypes form
`{{email}}`	Contact email
`{{brand}}`	Org brand name (`orgName`)
`{{legal_entity}}`	`legalEntityName`
`{{type_label}}`	Admin type label (back-compat)
`{{type_title}}`	`copy.type_title`
`{{success_button}}`	Ready-made CTA anchor when text + href are set; uses class `artamail-success-cta` and `target="_top"` (hosted UI renders in an iframe)
`{{success_button_class}}`	Literal class name `artamail-success-cta` for your own `<a>` markup; add `target="_top"`when hosted inside ArtaMail's iframe
`{{success_button_text}}`	`copy.success_button_text`
`{{success_button_href}}`	`copy.success_button_href` (escaped)

Errors

Status	Description
`400`	Invalid or expired token
`500`	Server error loading preferences