Marketing (experimental)

Subscribe a contact to a list (creating or updating the contact)

EXPERIMENTAL — enabled account by account; without it every call answers 403 module_disabled. Scopes read:contacts / write:contacts. On a list with double opt-in the subscription stays pending, and this call does NOT send a confirmation email (the confirmation flow is not available yet). Without double opt-in it is subscribed at once. Someone who unsubscribed through the link or the preference center, complained, or bounced is not subscribed again by the API (409).

post/lists/{id}/subscribe

Request

  • Base URL: https://api.oveyon.com/v1
  • URL: https://api.oveyon.com/v1/lists/{id}/subscribe
  • Auth: HTTP bearer

Path parameters

idinteger required

Request body

emailstring required

Required. Normalized before matching (case does not matter): only ASCII whitespace (space, TAB, LF, VT, FF, CR) is trimmed from the ends — a Unicode space at either end (NBSP, U+3000…) is not trimmed and the call is 400 invalid_email. ASCII only, the local part and the domain: an internationalized domain (IDN) enters only in its xn-- form (ana@xn--exmple-cua.com); ana@exämple.com is refused with 400 invalid_email and reason: address_not_ascii. The same holds when finding, tagging, unsubscribing and deleting a contact: only the ASCII form is looked up.

firstNamestring nullable
lastNamestring nullable
attributesobject nullable

Shallow merge into the stored properties. Names: ^[a-z][a-zA-Z0-9_]{0,63}$, never email/firstName/lastName. A new name is registered with the type of its first value.

externalIdstring nullable

Response

The subscription

contactIdinteger required
listIdinteger required
status'pending' | 'subscribed' required

pending on a list with double opt-in — and NO confirmation email is sent by this call. Also pending when the person was already pending on this list (e.g. they filled your form and did not confirm yet), on any list: only their own confirmation or their preference center turns pending into subscribed, never an API call or an import.

changedboolean required
contactCreatedboolean required

Changes

No recorded changes to this operation across all 1 revision of this API.