Recevoir des e-mails : Routes

Run Commands

Le point d'entrée unique pour lire et gérer une boîte aux lettres. Envoyez de 1 à 20 commandes dans une requête et recevez un résultat par commande.

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

Chaque action sur la boîte aux lettres (lister, lire, rechercher, marquer, déplacer, envoyer, répondre…) est une commande envoyée à cette route. Les pages sous celle-ci documentent chaque commande et ses arguments.

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 body

  • commandsobject[]obligatoire

    De 1 à 20 commandes, exécutées dans l'ordre.

  • commands[].commandstringobligatoire

    Le nom de la commande, par exemple list_threads.

  • commands[].argsobjectfacultatif

    Les arguments de la commande. N'importe quelle 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',
  {
    commands: [
      {
        command: "list_folders"
      },
      {
        command: "get_counters"
      }
    ]
  },
  { headers: { Authorization: process.env.SENDCOREX_TOKEN } },
);

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_folders",
      "id": "0",
      "type": "SUCCESS",
      "data": {
        "folders": [
          {
            "folder": "INBOX",
            "name": "INBOX",
            "system": true,
            "total": 12,
            "unread": 3
          }
        ]
      }
    },
    {
      "command": "get_counters",
      "id": "1",
      "type": "SUCCESS",
      "data": {
        "total": 12,
        "unread": 3,
        "size_bytes": 482113,
        "folders": {
          "INBOX": {
            "total": 12,
            "unread": 3,
            "size_bytes": 482113
          }
        }
      }
    }
  ]
}

Champs de la réponse

  • type

    Toujours SUCCESS lorsque 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[].data

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

  • results[].code

    Le code d'erreur. Présent uniquement quand type vaut ERROR.

  • results[].message

    Un message d'erreur lisible. Présent uniquement quand type vaut ERROR.

Authentification

Chaque route de commandes nécessite un access token. Le token détermine la boîte aux lettres utilisée : aucun argument ne permet de sélectionner un autre utilisateur.

  • Authorization

    Envoyez Authorization: <token> ou Authorization: Bearer <token>.

  • Format du token

    S.C.G. suivi de 100 caractères. Il identifie le propriétaire (utilisateur + expéditeur).

  • Expiration

    Les access tokens sont valables 1 heure. Quand l'un d'eux expire, vous recevez TOKEN_EXPIRED : appelez Refresh Token et relancez la requête.

!

Le token résolu est mis en cache jusqu'à 1 heure, donc un token révoqué peut continuer à fonctionner jusqu'à l'expiration de ce cache.

Accès en lecture seule

Un token créé en Lecture seule, ou une application autorisée en Lecture seule, ne peut que lire la boîte.

Commandes autorisées

whoami
list_folders
get_counters
list_threads
get_thread
list_messages
get_messages
search
get_attachment
get_raw_source
list_drafts
get_draft
get_tracking
list_activity
activity_counts
list_contacts
count_contacts
get_mailbox_contact
list_segments
get_audience
check_recipients
get_delivery_status
get_contact_events
get_trust
list_trust
list_junk
blocked_junk_count
list_top_senders
get_filter_mode
list_signatures
get_conversation
list_assignees
list_conversations
list_conversation_notes
list_rules
get_rule
rule_options
test_rule
list_templates
get_template
list_labels
get_contact
list_followups
get_unsubscribe_options
list_unsubscribed
!

Toute commande d’écriture renvoie READ_ONLY_ACCESS (HTTP 403 sur la route d’envoi de pièce jointe).

i

Dans le MCP, les tools d’écriture n’apparaissent pas pour une connexion en Lecture seule.

Réutiliser un résultat avec $ref

N'importe quelle valeur dans args peut être {"$ref": "<id>", "path": "<path>"}. Elle est remplacée par la valeur trouvée à path dans le résultat de la commande ayant cet id. Dans path, * parcourt une liste et aplatit le résultat. Vous pouvez ainsi lister et lire en une seule requête.

Body de la requête

{
  "commands": [
    {
      "command": "list_threads",
      "args": {
        "limit": 5
      },
      "id": "a"
    },
    {
      "command": "get_messages",
      "args": {
        "ids": {
          "$ref": "a",
          "path": "threads/*/last_message_uid"
        }
      },
      "id": "b"
    }
  ]
}
  • $ref

    L'id d'une commande précédente dans la même requête.

  • path

    Chemin séparé par des barres obliques dans ce résultat. * parcourt chaque élément d'une liste.

Rate limits et cache

Les limites s'appliquent par IP + utilisateur + expéditeur. Il n'y a pas de file d'attente : en cas de dépassement, la requête est rejetée avec HTTP 429 et un header Retry-After.

  • 15 requêtes / seconde

    Pic de 15. Les réponses servies depuis le cache comptent aussi.

  • 15 en cours

    Au maximum 15 requêtes traitées en même temps.

  • Regrouper plutôt que boucler

    Envoyez jusqu'à 20 commandes par requête au lieu d'une requête par action.

  • Cache de lecture : 1,5 s

    La même lecture (même commande et mêmes args) dans un délai de 1,5 seconde renvoie le même résultat. Cela concerne list_folders, get_counters, list_threads, list_messages, get_thread, get_messages, search, get_trust et list_trust.

  • Déduplication des écritures : 1,5 s

    La même écriture répétée dans un délai de 1,5 seconde ne s'exécute qu'une fois : un polling qui envoie deux fois le même reply n'envoie pas deux e-mails.

  • Invalidation du cache

    Toute commande d'écriture vide immédiatement le cache de lecture de cette boîte aux lettres, donc la lecture suivante voit le nouvel état.

i

Les e-mails remis dans la boîte aux lettres, ou les modifications faites dans le webmail, apparaissent dans les lectures en moins de 1,5 seconde.

Conventions

Ces règles sont communes à toutes les commandes.

  • Dossiers système

    INBOX, Sent, Archive, Trash, Drafts, Spam, Promotions et Snoozed. Les alias comme inbox, archived, draft, junk et promotion sont acceptés. Un dossier personnalisé est référencé par son slug ou par son nom.

  • Pagination

    limit va de 1 à 100 (25 par défaut). La réponse contient has_more et next_cursor : envoyez next_cursor comme cursor lors de l'appel suivant.

  • Actions groupées

    Les commandes d'action acceptent ids (une liste de 100 au maximum) ou id (un seul) et répondent élément par élément avec items, ok_count et failed_count.

  • scope

    thread s'applique à toute la conversation dans le dossier source. message s'applique uniquement à l'id indiqué.

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 body n'est pas {"commands":[...]} ou contient plus de 20 commandes.

  • 401MISSING_AUTH_HEADER

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

  • 401INVALID_TOKEN

    Le token est mal formé, inconnu ou révoqué.

  • 401TOKEN_EXPIRED

    L'access token a expiré. Appelez Refresh Token et relancez la requête.

  • 429RATE_LIMITED

    Plus de 15 requêtes/s ou 15 en cours pour la même IP + boîte aux lettres. 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.

  • CMDINVALID_ARGS

    Un argument obligatoire est manquant ou invalide.

  • CMDREAD_ONLY_ACCESS

    Le token ou l’application a un accès en Lecture seule et la commande écrit. Sur la route d’envoi de pièce jointe, c’est HTTP 403.

  • CMDINTERNAL

    Erreur serveur. Le détail est uniquement écrit dans le log du serveur.