Contacts : segments

Exécuter un segment

Obtenez maintenant les contacts qui correspondent à un segment enregistré. Même sortie et même pagination que Query Contacts.

POSThttps://g.sendcorex.com/v1/contactscommand: run_segment
i

Nécessite le scope contact:read sur votre API key.

Arguments

  • segment_idstringobligatoire

    Le segment à exécuter.

    ex. : "engaged-vips"

  • limitnumberfacultatif

    Taille de page, de 1 à 1000. 50 par défaut.

  • cursorstringfacultatif

    Le next_cursor de la page précédente.

  • selectstring[]facultatif

    Ne renvoie que ces parties de chaque contact, par exemple ["status", "fields.plan", "stats.open_count"]. email revient toujours. Sans lui, vous obtenez le contact complet.

Démarrage rapide

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/contacts',
  {
    commands: [
      {
        command: "run_segment",
        args: {
          segment_id: "engaged-vips",
          select: [
            "first_name",
            "stats.open_rate"
          ],
          limit: 500
        }
      }
    ]
  },
  { 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": "run_segment",
      "id": "0",
      "type": "SUCCESS",
      "took_ms": 14,
      "data": {
        "contacts": [
          {
            "email": "ana@acme.com",
            "first_name": "Ana",
            "stats": {
              "open_rate": 0.58
            }
          }
        ],
        "has_more": false,
        "next_cursor": null,
        "plan": {
          "driver": "tag:vip",
          "examined": 412,
          "keys_only": false,
          "ms": {
            "scan": 4,
            "fetch": 9,
            "filter": 1,
            "total": 14
          }
        }
      }
    }
  ]
}

Champs de la réponse

  • contacts

    Les contacts trouvés. Complets, ou uniquement les parties demandées avec select.

  • has_more / next_cursor

    Pagination. Tant que has_more vaut true, envoyez next_cursor comme cursor avec les mêmes where et sort.

  • plan.driver

    L'index que le serveur a choisi de parcourir, par exemple tag:vip ou list:customers.

  • plan.examined

    Combien d'entrées d'index ont été lues pour remplir cette page.

  • plan.keys_only

    true quand la page a été servie uniquement depuis l'index, sans charger les contacts.

  • plan.ms

    Temps passé à parcourir, charger, filtrer et au total, en millisecondes.

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 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 requis par cette commande. Les autres commandes de la requête s'exécutent quand même.

  • CMDINVALID_ARGS

    Un argument obligatoire est manquant ou invalide : email, valeur de champ, option d'enum, clé de where, id de liste…

  • CMDNOT_FOUND

    Le contact, la liste, le champ ou le segment n'existe pas.

  • CMDINVALID_CURSOR

    Le cursor est mal formé ou appartient à une autre requête ou à un autre compte.

  • CMDINTERNAL

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