E-Mails empfangen: Routen
Run Commands
Der zentrale Einstiegspunkt zum Lesen und Verwalten eines Postfachs. Senden Sie 1 bis 20 Befehle in einer Anfrage und erhalten Sie ein Ergebnis pro Befehl.
https://g.sendcorex.com/v1Jede Aktion im Postfach (auflisten, lesen, suchen, markieren, verschieben, senden, antworten…) ist ein Befehl, der an diese Route gesendet wird. Die Seiten unterhalb dieser Seite dokumentieren jeden Befehl und seine Argumente.
Fehler werden pro Befehl gemeldet. Ein fehlgeschlagener Befehl stoppt die anderen nicht, und der HTTP-Status bleibt 200.
Body-Parameter
commandsobject[]erforderlich1 bis 20 Befehle, die der Reihe nach ausgeführt werden.
commands[].commandstringerforderlichDer Befehlsname, zum Beispiel
list_threads.commands[].argsobjectoptionalDie Argumente des Befehls. Jeder Wert kann eine
$refauf das Ergebnis eines früheren Befehls sein.commands[].idstringoptionalIhre eigene Kennung für das Ergebnis. Standardmäßig der Index (
"0","1"…). Erforderlich, wenn Sie$refverwenden möchten.
Schnellstart
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);
}Antwort
{
"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
}
}
}
}
]
}Antwortfelder
typeImmer
SUCCESS, wenn die Anfrage selbst angenommen wurde.results[].commandDer Befehl, der dieses Ergebnis erzeugt hat.
results[].idDie von Ihnen gesendete
idoder der Index des Befehls.results[].typeSUCCESSoderERROR.results[].dataDie Ausgabe des Befehls. Nur vorhanden, wenn
typeden WertSUCCESShat.results[].codeDer Fehlercode. Nur vorhanden, wenn
typeden WertERRORhat.results[].messageEine lesbare Fehlermeldung. Nur vorhanden, wenn
typeden WertERRORhat.
Authentifizierung
Jede Befehlsroute braucht einen Access Token. Der Token bestimmt, welches Postfach verwendet wird: Kein Argument wählt einen anderen Benutzer aus.
AuthorizationSenden Sie
Authorization: <token>oderAuthorization: Bearer <token>.Token-FormatS.C.G.gefolgt von 100 Zeichen. Es identifiziert den Inhaber (Benutzer + Absender).GültigkeitAccess Tokens gelten 1 Stunde. Läuft einer ab, erhalten Sie
TOKEN_EXPIRED: Rufen Sie Refresh Token auf und wiederholen Sie die Anfrage.
Der aufgelöste Token wird bis zu 1 Stunde gecacht, daher kann ein widerrufener Token weiter funktionieren, bis dieser Cache abläuft.
Nur-Lese-Zugriff
Ein als Nur lesen erstelltes Token oder eine als Nur lesen autorisierte App kann das Postfach nur lesen.
Erlaubte Befehle
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_unsubscribedJeder schreibende Befehl antwortet mit READ_ONLY_ACCESS (HTTP 403 bei der Route zum Hochladen von Anhängen).
Im MCP werden die schreibenden Tools bei einer Nur-lesen-Verbindung nicht angezeigt.
Ein früheres Ergebnis mit $ref verwenden
Jeder Wert in args kann {"$ref": "<id>", "path": "<path>"} sein. Er wird durch den Wert ersetzt, der unter path im Ergebnis des Befehls mit dieser id steht. In path durchläuft * eine Liste und flacht das Ergebnis ab. So können Sie in einer einzigen Anfrage auflisten und lesen.
Request-Body
{
"commands": [
{
"command": "list_threads",
"args": {
"limit": 5
},
"id": "a"
},
{
"command": "get_messages",
"args": {
"ids": {
"$ref": "a",
"path": "threads/*/last_message_uid"
}
},
"id": "b"
}
]
}$refDie
ideines früheren Befehls in derselben Anfrage.pathDurch Schrägstriche getrennter Pfad in diesem Ergebnis.
*durchläuft jedes Element einer Liste.
Rate Limits und Cache
Die Limits gelten pro IP + Benutzer + Absender. Es gibt keine Warteschlange: Wenn Sie darüber liegen, wird die Anfrage mit HTTP 429 und einem Retry-After-Header abgelehnt.
15 Anfragen / SekundeSpitze von 15. Aus dem Cache bediente Antworten zählen ebenfalls.
15 gleichzeitigHöchstens 15 Anfragen werden gleichzeitig verarbeitet.
Bündeln statt SchleifenSenden Sie bis zu 20 Befehle pro Anfrage statt einer Anfrage pro Aktion.
Lese-Cache: 1,5 sDerselbe Lesevorgang (gleicher Befehl und gleiche args) innerhalb von 1,5 Sekunden liefert dasselbe Ergebnis. Das betrifft
list_folders,get_counters,list_threads,list_messages,get_thread,get_messages,search,get_trustundlist_trust.Schreib-Deduplizierung: 1,5 sDerselbe Schreibvorgang, der innerhalb von 1,5 Sekunden wiederholt wird, läuft nur einmal. Ein Polling, das denselben
replyzweimal sendet, verschickt also keine zwei E-Mails.Cache-InvalidierungJeder Schreibbefehl leert sofort den Lese-Cache dieses Postfachs, sodass der nächste Lesevorgang den neuen Zustand sieht.
In das Postfach zugestellte E-Mails oder Änderungen im Webmail erscheinen innerhalb von 1,5 Sekunden in Lesevorgängen.
Konventionen
Diese Regeln gelten für alle Befehle.
SystemordnerINBOX,Sent,Archive,Trash,Drafts,Spam,PromotionsundSnoozed. Aliase wieinbox,archived,draft,junkundpromotionwerden akzeptiert. Ein eigener Ordner wird über seinen Slug oder seinen Namen referenziert.Paginierunglimitreicht von 1 bis 100 (Standard 25). Die Antwort enthälthas_moreundnext_cursor: Senden Sienext_cursorbeim nächsten Aufruf alscursor.StapelaktionenAktionsbefehle akzeptieren
ids(eine Liste mit bis zu 100) oderid(eine einzelne) und antworten pro Element mititems,ok_countundfailed_count.scopethreadgilt für die gesamte Konversation im Quellordner.messagegilt nur für die angegebene id.
Fehler
Fehler auf HTTP-Ebene liefern type, code und message. Mit CMD markierte Fehler kommen im Befehlsergebnis zurück, mit HTTP 200.
- 400
INVALID_JSONDer Body ist nicht {"commands":[...]} oder enthält mehr als 20 Befehle.
- 401
MISSING_AUTH_HEADEREs wurde kein Authorization-Header gesendet.
- 401
INVALID_TOKENDer Token ist fehlerhaft, unbekannt oder widerrufen.
- 401
TOKEN_EXPIREDDer Access Token ist abgelaufen. Rufen Sie Refresh Token auf und wiederholen Sie die Anfrage.
- 429
RATE_LIMITEDMehr als 15 Anfragen/s oder 15 gleichzeitig laufende Anfragen für dieselbe IP + dasselbe Postfach. Warten Sie die in Retry-After angegebene Anzahl Sekunden.
- 503
AUTH_UNAVAILABLEDie Authentifizierung ist vorübergehend nicht verfügbar. Versuchen Sie es erneut.
- CMD
UNKNOWN_COMMANDDer Befehlsname existiert nicht.
- CMD
INVALID_ARGSEin erforderliches Argument fehlt oder ist ungültig.
- CMD
READ_ONLY_ACCESSDas Token oder die App hat Nur-lesen-Zugriff und der Befehl schreibt. Bei der Route zum Hochladen von Anhängen ist es HTTP 403.
- CMD
INTERNALServerfehler. Die Details werden nur ins Server-Log geschrieben.