Email

Endpointhttps://api.kontier.eu/v1

GET

https://api.kontier.eu/v1

/mail/consent

Keyset-paginated list of the org's current marketing-consent states, filterable by state, purpose, and email substring. Requires mail.read.

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

Opaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.

state

string

Filter by state: opted_in|soft_opt_in|opted_out|unknown.

purpose

string

Filter by consent purpose; defaults to all.

email

string · maxLength: 320

Case-insensitive substring match on the recipient address.

sort

string

Ordering: updated_at, email, state, basis or source, each with an optional :asc/:desc suffix (default updated_at:desc). An unknown value is rejected. email orders by lower(email), the key consent is unique on. source is nullable: rows without one are grouped together and sort last ascending, first descending. Cursors are bound to the ordering that issued them, so changing sort mid-walk needs a fresh first page.

X-Workspace-Id

string

Selects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.

Workspace UUID or slug.

array | null · required

object · required

PUT

https://api.kontier.eu/v1

/mail/consent

Records ONE recipient's marketing-consent state with proof rules — never a bulk opt-in. Recording opted_in REQUIRES proof_text: without it the call is refused with 422 CONSENT_PROOF_REQUIRED rather than quietly recorded as unknown (send state=unknown for that). soft_opt_in cannot be set by hand. The change is appended to the demonstrability record. Requires mail.consent.manage.

X-Workspace-Id

string

Workspace UUID or slug.

email

string · maxLength: 320 · required

The recipient address (required).

state

string · required

The state to record: opted_in | opted_out | unknown. soft_opt_in is not manually settable (it is seeded from sales).

customer_id

string · uuid

The customer this address belongs to, when known.

proof_text

string

The consent statement the recipient agreed to. Required to record opted_in; without proof an opt-in lands as unknown (§4.1).

purpose

string

Consent purpose; defaults to marketing_email.

object · required

PUT/mail/consent

curl --request PUT \
  --url https://api.kontier.eu/v1/mail/consent \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "email": "email",
  "proof_text": "proof_text",
  "purpose": "purpose",
  "state": "state"
}
'

shell

Example Request Body

{
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "email": "email",
  "proof_text": "proof_text",
  "purpose": "purpose",
  "state": "state"
}

json

Example Responses

{
  "data": {
    "basis": "basis",
    "customer_id": "customer_id",
    "effective_at": "2024-08-25T15:00:00Z",
    "email": "email",
    "id": "id",
    "purpose": "purpose",
    "source": "source",
    "state": "state",
    "updated_at": "2024-08-25T15:00:00Z",
    "withdrawn_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

GET

https://api.kontier.eu/v1

/mail/consent/history

The append-only log of marketing-consent changes: what each state moved from and to, who moved it, and the evidence that change carried (the statement agreed to, the IP, the user agent). This is the record GDPR Art 7(1) demonstrability is served from — the current state alone cannot show what changed when. Filter by email to get one recipient's trail. Keyset-paginated, newest first. Requires mail.read.

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

email

string · maxLength: 320

Filter to one exact recipient address (case-insensitive). This is the usual call: the history is opened from a single permission row.

purpose

string

Filter by consent purpose; defaults to all.

customer_id

string · uuid

Filter to one customer's transitions.

X-Workspace-Id

string

Workspace UUID or slug.

array | null · required

object · required

GET/mail/consent/history

curl --request GET \
  --url https://api.kontier.eu/v1/mail/consent/history

shell

Example Responses

{
  "data": [
    {
      "actor_id": "actor_id",
      "actor_kind": "actor_kind",
      "basis": "basis",
      "captured_ip": "captured_ip",
      "captured_user_agent": "captured_user_agent",
      "consent_id": "consent_id",
      "created_at": "2024-08-25T15:00:00Z",
      "customer_id": "customer_id",
      "email": "email",
      "evidence_ref": "evidence_ref",
      "from_state": "from_state",
      "id": "id",
      "occurred_at": "2024-08-25T15:00:00Z",
      "origin_sale_ref": "origin_sale_ref",
      "proof_text": "proof_text",
      "purpose": "purpose",
      "source": "source",
      "synthetic": true,
      "to_state": "to_state"
    }
  ],
  "pagination": {
    "counts": {
      "key": {
        "key": 0
      }
    },
    "cursor": "cursor",
    "has_more": true,
    "total_count": 0
  }
}

json

application/json

Audiences Files

List marketing consent

GET

https://api.kontier.eu/v1

/mail/consent

Keyset-paginated list of the org's current marketing-consent states, filterable by state, purpose, and email substring. Requires mail.read.

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

state

string

Filter by state: opted_in|soft_opt_in|opted_out|unknown.

purpose

string

Filter by consent purpose; defaults to all.

email

string · maxLength: 320

Case-insensitive substring match on the recipient address.

sort

string

X-Workspace-Id

string

Workspace UUID or slug.

array | null · required

object · required

Record a recipient's consent

PUT

https://api.kontier.eu/v1

/mail/consent

X-Workspace-Id

string

Workspace UUID or slug.

email

string · maxLength: 320 · required

The recipient address (required).

state

string · required

The state to record: opted_in | opted_out | unknown. soft_opt_in is not manually settable (it is seeded from sales).

customer_id

string · uuid

The customer this address belongs to, when known.

proof_text

string

The consent statement the recipient agreed to. Required to record opted_in; without proof an opt-in lands as unknown (§4.1).

purpose

string

Consent purpose; defaults to marketing_email.

object · required

List marketing-consent transitions

GET

https://api.kontier.eu/v1

/mail/consent/history

limit

integer · min: 1

Page size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.

Example: 50

cursor

string

email

string · maxLength: 320

Filter to one exact recipient address (case-insensitive). This is the usual call: the history is opened from a single permission row.

purpose

string

Filter by consent purpose; defaults to all.

customer_id

string · uuid

Filter to one customer's transitions.

X-Workspace-Id

string

Workspace UUID or slug.

array | null · required

object · required

Email

List marketing consent

List marketing consent › query Parameters

List marketing consent › Headers

List marketing consent › Responses

Record a recipient's consent

Record a recipient's consent › Headers

Record a recipient's consent › Request Body

Record a recipient's consent › Responses

List marketing-consent transitions

List marketing-consent transitions › query Parameters

List marketing-consent transitions › Headers

List marketing-consent transitions › Responses

Email

List marketing consent

List marketing consent › query Parameters

List marketing consent › Headers

List marketing consent › Responses

Record a recipient's consent

Record a recipient's consent › Headers

Record a recipient's consent › Request Body

Record a recipient's consent › Responses

List marketing-consent transitions

List marketing-consent transitions › query Parameters

List marketing-consent transitions › Headers

List marketing-consent transitions › Responses