Tracking Preferences : Écriture

Définir les préférences

Enregistrez le choix de tracking d'un destinataire, par exemple le consentement recueilli dans vos propres formulaires ou votre CRM.

POSThttps://g.sendcorex.com/v1/privacycommand: set_preferences
i

Nécessite le scope privacy:write sur votre API key.

i

N'envoyez que ce qui a changé : un champ omis garde sa valeur actuelle. Renvoyer les mêmes valeurs ne change rien et changed revient à false.

i

Les changements faits ici sont enregistrés avec source: "api" dans l'historique. Ils ne déclenchent pas le webhook tracking_preferences_updated, donc une synchronisation CRM ne boucle jamais.

Arguments

  • emailstringobligatoire

    L'adresse du destinataire.

    ex. : "jane.doe@example.com"

  • track_opensbooleanfacultatif

    true autorise le suivi des ouvertures, false le refuse.

    ex. : true

  • track_clicksbooleanfacultatif

    true autorise le suivi des clics, false le refuse.

    ex. : true

Démarrage rapide

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/privacy',
  {
    commands: [
      {
        command: "set_preferences",
        args: {
          email: "jane.doe@example.com",
          track_opens: true,
          track_clicks: true
        }
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);

const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);

Réponse

{
  "type": "SUCCESS",
  "results": [
    {
      "command": "set_preferences",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 6,
      "data": {
        "changed": true,
        "preference": {
          "email": "jane.doe@example.com",
          "track_opens": true,
          "track_clicks": true,
          "source": "api",
          "updated_at": "2026-10-24T08:02:19.744Z"
        }
      }
    }
  ]
}

Champs de la réponse

  • changed

    false lorsque le destinataire avait déjà ces valeurs (rien n'a été écrit).

  • preference

    L'état après l'appel.

  • preference.email

    L'adresse du destinataire, en minuscules.

  • preference.track_opens

    true le destinataire autorise le suivi des ouvertures, false il l'a refusé, null il n'a jamais choisi.

  • preference.track_clicks

    true le destinataire autorise le suivi des clics, false il l'a refusé, null il n'a jamais choisi.

  • preference.source

    Qui a fait le changement : page (le destinataire, sur la page des préférences de tracking), api (vous, avec Set Preferences) ou dashboard.

  • preference.updated_at

    Quand le changement a été fait. ISO 8601, UTC.

Impact sur vos envois

  • Le refus l'emporte toujours

    Quand track_opens ou track_clicks vaut false, ce tracking est retiré de l'e-mail même si votre envoi le demande avec "track_opens": true.

  • Jamais choisi

    Quand la valeur est null (ou que le destinataire n'a aucune préférence), c'est votre envoi qui décide, exactement comme avant.

  • Nécessite notre moteur de désabonnement

    Les préférences s'appliquent aux envois avec "unsubscribe": true. C'est aussi ce qui place le lien des préférences dans l'e-mail.

  • Votre valeur par défaut

    Pour les règles d'opt-in (par exemple en France), envoyez "track_opens": false et "track_clicks": false tant que le destinataire ne l'a pas autorisé, et lisez la préférence avec Get Many avant l'envoi.

Erreurs

Les erreurs au niveau HTTP renvoient type, code et message. Les erreurs marquées CMD reviennent dans le résultat de la commande, avec HTTP 200.

  • 401INVALID_API_KEY

    L'API key n'existe pas, a été révoquée ou a été désactivée dans le dashboard.

  • 429RATE_LIMITED

    Plus de 15 requêtes/s ou 15 simultanées pour la même IP + API key. Attendez le nombre de secondes indiqué dans Retry-After.

  • CMDMISSING_SCOPE

    L'API key n'a pas le scope de cette commande (`privacy:read` pour lire, `privacy:write` pour modifier).

  • CMDINVALID_ARGS

    Un argument est invalide : `email` manquant ou mal formé, plus de 100 `emails`, `track_opens` qui ne vaut pas `true`/`false`, limit hors limites…

  • CMDINTERNAL

    Erreur serveur. Le détail n'est écrit que dans le log du serveur.