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.
https://g.sendcorex.com/v1Chaque 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.
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[]obligatoireDe 1 à 20 commandes, exécutées dans l'ordre.
commands[].commandstringobligatoireLe nom de la commande, par exemple
list_threads.commands[].argsobjectfacultatifLes arguments de la commande. N'importe quelle valeur peut être un
$refvers le résultat d'une commande précédente.commands[].idstringfacultatifVotre 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
typeToujours
SUCCESSlorsque la requête elle-même a été acceptée.results[].commandLa commande qui a produit ce résultat.
results[].idL'
idque vous avez envoyé, ou l'index de la commande.results[].typeSUCCESSouERROR.results[].dataLa sortie de la commande. Présente uniquement quand
typevautSUCCESS.results[].codeLe code d'erreur. Présent uniquement quand
typevautERROR.results[].messageUn message d'erreur lisible. Présent uniquement quand
typevautERROR.
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.
AuthorizationEnvoyez
Authorization: <token>ouAuthorization: Bearer <token>.Format du tokenS.C.G.suivi de 100 caractères. Il identifie le propriétaire (utilisateur + expéditeur).ExpirationLes 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_unsubscribedToute commande d’écriture renvoie READ_ONLY_ACCESS (HTTP 403 sur la route d’envoi de pièce jointe).
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"
}
]
}$refL'
idd'une commande précédente dans la même requête.pathChemin 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 / secondePic de 15. Les réponses servies depuis le cache comptent aussi.
15 en coursAu maximum 15 requêtes traitées en même temps.
Regrouper plutôt que bouclerEnvoyez jusqu'à 20 commandes par requête au lieu d'une requête par action.
Cache de lecture : 1,5 sLa 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_trustetlist_trust.Déduplication des écritures : 1,5 sLa 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
replyn'envoie pas deux e-mails.Invalidation du cacheToute commande d'écriture vide immédiatement le cache de lecture de cette boîte aux lettres, donc la lecture suivante voit le nouvel état.
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èmeINBOX,Sent,Archive,Trash,Drafts,Spam,PromotionsetSnoozed. Les alias commeinbox,archived,draft,junketpromotionsont acceptés. Un dossier personnalisé est référencé par son slug ou par son nom.Paginationlimitva de 1 à 100 (25 par défaut). La réponse contienthas_moreetnext_cursor: envoyeznext_cursorcommecursorlors de l'appel suivant.Actions groupéesLes commandes d'action acceptent
ids(une liste de 100 au maximum) ouid(un seul) et répondent élément par élément avecitems,ok_countetfailed_count.scopethreads'applique à toute la conversation dans le dossier source.messages'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.
- 400
INVALID_JSONLe body n'est pas {"commands":[...]} ou contient plus de 20 commandes.
- 401
MISSING_AUTH_HEADERAucun header Authorization n'a été envoyé.
- 401
INVALID_TOKENLe token est mal formé, inconnu ou révoqué.
- 401
TOKEN_EXPIREDL'access token a expiré. Appelez Refresh Token et relancez la requête.
- 429
RATE_LIMITEDPlus 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.
- 503
AUTH_UNAVAILABLEL'authentification est temporairement indisponible. Réessayez.
- CMD
UNKNOWN_COMMANDLe nom de la commande n'existe pas.
- CMD
INVALID_ARGSUn argument obligatoire est manquant ou invalide.
- CMD
READ_ONLY_ACCESSLe 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.
- CMD
INTERNALErreur serveur. Le détail est uniquement écrit dans le log du serveur.