Subscribers

Add or update a subscriber

Permission required: subscribers:write.

By default the person enters pending and receives a confirmation email. double_opt_in: false subscribes them straight away — to be used only if consent was collected elsewhere, and the caller then bears responsibility for it.

An address on the suppression list, unsubscribed, or returned as a hard bounce is refused.

post/api/v1/subscribers

Request

  • Base URL: https://mailcheer.com
  • URL: https://mailcheer.com/api/v1/subscribers
  • Auth: one of:
    • HTTP bearer
    • API key in header X-Api-Key

Request body

emailstring email required

Required. Lower-cased on save.

firstNamestring
lastNamestring
prenomstring

Alias of firstName. Fill in only one of the two.

nomstring

Alias of lastName. Fill in only one of the two.

tagsstring[]

Workspace tags. The ones that do not exist yet are created.

fieldsobject

Custom fields, by their technical key. Unknown keys create nothing: they come back in ignored_fields.

double_opt_inboolean

false subscribes straight away, with no confirmation email. The caller then bears responsibility for the consent.

Example request

{
  "email": "marie@example.com",
  "firstName": "Marie",
  "lastName": "Dupont",
  "prenom": "Marie",
  "nom": "Dupont",
  "tags": [
    "customers",
    "paris-store"
  ],
  "fields": {
    "city": "Ajaccio"
  },
  "double_opt_in": true
}

Response

The subscriber already existed and has been updated.

updatedboolean

true if the subscriber already existed.

confirmation_sentboolean

true if a confirmation email went out with THIS call. Exactly when confirmation_not_sent_reason is null.

confirmation_not_sent_reason'not_needed' | 'recently_sent' | 'daily_limit' | 'send_failed' | 'null' nullable

Why no confirmation went out with this call: not_needed (already confirmed, or double_opt_in: false), recently_sent (one went out less than 2 minutes ago), daily_limit (3 per address per 24 hours, all channels combined), send_failed (the provider refused it; call again later). null when one went out.

confirmation_retry_atstring date-time nullable

When a new call can send one again (ISO 8601): set only for recently_sent and daily_limit, otherwise null.

ignored_fieldsstring[]

Keys of fields unknown to this workspace, written nowhere.

Changes

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