Senders : routes

Run Commands

Le point d'entrée unique pour les senders. Envoyez de 1 à 20 commandes dans une requête et recevez un résultat par commande.

POSThttps://g.sendcorex.com/v1/sender
i

Même enveloppe que Domains, Contacts et Logs. Les pages suivantes documentent chaque commande.

i

Les erreurs sont signalées par commande. Une commande qui échoue n'arrête pas les autres, et le statut HTTP reste 200.

Paramètres du corps

  • commandsobject[]obligatoire

    De 1 à 20 commandes, exécutées dans l'ordre. Le corps entier peut faire jusqu'à 1 Mo.

  • commands[].commandstringobligatoire

    list_senders, get_sender, create_sender, update_sender, update_sender_description ou delete_sender.

  • commands[].argsobjectfacultatif

    Les arguments de la commande. Toute valeur peut être un $ref vers le résultat d'une commande précédente.

  • commands[].idstringfacultatif

    Votre propre identifiant pour le résultat. Par défaut, l'index ("0", "1"…). Obligatoire si vous voulez utiliser $ref.

Démarrage rapide

import axios from 'axios';

const response = await axios.post(
  'https://g.sendcorex.com/v1/sender',
  {
    commands: [
      {
        command: "list_senders",
        id: "all"
      },
      {
        command: "get_sender",
        id: "one",
        args: {
          sender_id: "K7Q2M9XR4TB8WD1ZC6NF3HJP"
        }
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);

for (const result of response.data.results) {
  if (result.type !== 'SUCCESS') console.error(result.id, result.code, result.message);
  else console.log(result.id, result.data);
}

Réponse

{
  "type": "SUCCESS",
  "results": [
    {
      "command": "list_senders",
      "id": "all",
      "type": "SUCCESS",
      "took_ms": 5,
      "data": {
        "senders": [
          {
            "sender_id": "K7Q2M9XR4TB8WD1ZC6NF3HJP",
            "email": "hello@acme.com",
            "username": "hello",
            "domain": "acme.com",
            "from_name": "Acme",
            "reply_to": "support@acme.com",
            "description": "Product updates",
            "avatar_color": "#2F6FDB",
            "warmup_enabled": false,
            "reputation": {
              "delivered": 18420,
              "bounced": 131,
              "spam": 6,
              "received_messages": 2210,
              "total_emails": 18557,
              "has_minimum_volume": true,
              "delivery_rate": 99,
              "bounce_rate": 1,
              "spam_rate": 0,
              "engagement_rate": 12,
              "score": 100,
              "status": "Excellent"
            },
            "created_at": "2026-09-02T14:40:12.530Z",
            "updated_at": "2026-10-20T08:15:33.004Z"
          }
        ]
      }
    },
    {
      "command": "get_sender",
      "id": "one",
      "type": "SUCCESS",
      "took_ms": 2,
      "data": {
        "sender_id": "K7Q2M9XR4TB8WD1ZC6NF3HJP",
        "email": "hello@acme.com",
        "username": "hello",
        "domain": "acme.com",
        "from_name": "Acme",
        "reply_to": "support@acme.com",
        "description": "Product updates",
        "avatar_color": "#2F6FDB",
        "warmup_enabled": false,
        "reputation": {
          "delivered": 18420,
          "bounced": 131,
          "spam": 6,
          "received_messages": 2210,
          "total_emails": 18557,
          "has_minimum_volume": true,
          "delivery_rate": 99,
          "bounce_rate": 1,
          "spam_rate": 0,
          "engagement_rate": 12,
          "score": 100,
          "status": "Excellent"
        },
        "created_at": "2026-09-02T14:40:12.530Z",
        "updated_at": "2026-10-20T08:15:33.004Z"
      }
    }
  ]
}

Champs de la réponse

  • type

    Toujours SUCCESS quand la requête elle-même a été acceptée.

  • results[].command

    La commande qui a produit ce résultat.

  • results[].id

    L'id que vous avez envoyé, ou l'index de la commande.

  • results[].type

    SUCCESS ou ERROR.

  • results[].took_ms

    Temps passé par la commande dans le serveur.

  • results[].data

    La sortie de la commande. Présente uniquement quand type vaut SUCCESS.

  • results[].code / message

    L'erreur. Présente uniquement quand type vaut ERROR.

Authentification

Utilisez l'API key que vous créez dans le dashboard, sous Developers → API Keys, avec les scopes requis par les commandes.

  • Authorization

    Envoyez Authorization: <api key> ou Authorization: Bearer <api key>.

  • sender:read

    list_senders et get_sender.

  • sender:create

    create_sender.

  • sender:update

    update_sender et update_sender_description.

  • sender:delete

    delete_sender.

  • Tokens de boîte mail

    Le token du webmail ne fonctionne pas ici. Il est refusé avec WRONG_CREDENTIAL_TYPE.

  • IP autorisées

    Si la clé a une liste d'IP autorisées, les requêtes venant d'autres IP reçoivent 403 IP_NOT_ALLOWED.

Enchaîner avec $ref

Créez un sender et transmettez son id à la commande suivante dans la même requête.

create_sender → update_sender_description

{
  "commands": [
    {
      "command": "create_sender",
      "id": "new",
      "args": {
        "username": "news",
        "from_name": "Acme News",
        "reply_to": "news@acme.com",
        "domain": "acme.com"
      }
    },
    {
      "command": "update_sender_description",
      "args": {
        "sender_id": {
          "$ref": "new",
          "path": "sender_id"
        },
        "description": "Monthly newsletter"
      }
    }
  ]
}

Rate limits

  • 15 requêtes / seconde

    Par IP + API key. Au-delà, HTTP 429 avec un header Retry-After.

  • 15 simultanées

    Au maximum 15 requêtes traitées en même temps, par IP + API key.

  • Par commande, par compte

    create_sender et update_sender 10/min · update_sender_description 20/min · delete_sender 30/min. Au-delà, la commande répond RATE_LIMITED.

  • Pas de cache

    Chaque appel lit la base de données. Ce que vous obtenez est toujours à jour.

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.

  • 400INVALID_JSON

    Le corps n'est pas {"commands":[...]} ou dépasse 1 Mo.

  • 400INVALID_ARGS

    La requête ne contient aucune commande ou plus de 20.

  • 401MISSING_AUTH_HEADER

    Aucun header Authorization n'a été envoyé.

  • 401INVALID_API_KEY

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

  • 401API_KEY_EXPIRED

    L'API key a dépassé la date d'expiration définie dans le dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Un token de boîte mail a été envoyé. La Senders API nécessite une API key du dashboard.

  • 403IP_NOT_ALLOWED

    La requête provient d'une IP qui ne figure pas parmi les IP autorisées de la clé.

  • 403ACCOUNT_BLOCKED

    Le compte est bloqué.

  • 403MISSING_SCOPE

    La clé n'a aucun scope `sender:*`, donc aucune commande ne peut s'exécuter.

  • 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.

  • 503AUTH_UNAVAILABLE

    L'authentification est temporairement indisponible. Réessayez.

  • CMDUNKNOWN_COMMAND

    Le nom de la commande n'existe pas.

  • CMDINTERNAL

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