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.

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

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

i

Fehler werden pro Befehl gemeldet. Ein fehlgeschlagener Befehl stoppt die anderen nicht, und der HTTP-Status bleibt 200.

Body-Parameter

  • commandsobject[]erforderlich

    1 bis 20 Befehle, die der Reihe nach ausgeführt werden.

  • commands[].commandstringerforderlich

    Der Befehlsname, zum Beispiel list_threads.

  • commands[].argsobjectoptional

    Die Argumente des Befehls. Jeder Wert kann eine $ref auf das Ergebnis eines früheren Befehls sein.

  • commands[].idstringoptional

    Ihre eigene Kennung für das Ergebnis. Standardmäßig der Index ("0", "1"…). Erforderlich, wenn Sie $ref verwenden 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

  • type

    Immer SUCCESS, wenn die Anfrage selbst angenommen wurde.

  • results[].command

    Der Befehl, der dieses Ergebnis erzeugt hat.

  • results[].id

    Die von Ihnen gesendete id oder der Index des Befehls.

  • results[].type

    SUCCESS oder ERROR.

  • results[].data

    Die Ausgabe des Befehls. Nur vorhanden, wenn type den Wert SUCCESS hat.

  • results[].code

    Der Fehlercode. Nur vorhanden, wenn type den Wert ERROR hat.

  • results[].message

    Eine lesbare Fehlermeldung. Nur vorhanden, wenn type den Wert ERROR hat.

Authentifizierung

Jede Befehlsroute braucht einen Access Token. Der Token bestimmt, welches Postfach verwendet wird: Kein Argument wählt einen anderen Benutzer aus.

  • Authorization

    Senden Sie Authorization: <token> oder Authorization: Bearer <token>.

  • Token-Format

    S.C.G. gefolgt von 100 Zeichen. Es identifiziert den Inhaber (Benutzer + Absender).

  • Gültigkeit

    Access 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_unsubscribed
!

Jeder schreibende Befehl antwortet mit READ_ONLY_ACCESS (HTTP 403 bei der Route zum Hochladen von Anhängen).

i

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"
    }
  ]
}
  • $ref

    Die id eines früheren Befehls in derselben Anfrage.

  • path

    Durch 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 / Sekunde

    Spitze von 15. Aus dem Cache bediente Antworten zählen ebenfalls.

  • 15 gleichzeitig

    Höchstens 15 Anfragen werden gleichzeitig verarbeitet.

  • Bündeln statt Schleifen

    Senden Sie bis zu 20 Befehle pro Anfrage statt einer Anfrage pro Aktion.

  • Lese-Cache: 1,5 s

    Derselbe 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_trust und list_trust.

  • Schreib-Deduplizierung: 1,5 s

    Derselbe Schreibvorgang, der innerhalb von 1,5 Sekunden wiederholt wird, läuft nur einmal. Ein Polling, das denselben reply zweimal sendet, verschickt also keine zwei E-Mails.

  • Cache-Invalidierung

    Jeder Schreibbefehl leert sofort den Lese-Cache dieses Postfachs, sodass der nächste Lesevorgang den neuen Zustand sieht.

i

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.

  • Systemordner

    INBOX, Sent, Archive, Trash, Drafts, Spam, Promotions und Snoozed. Aliase wie inbox, archived, draft, junk und promotion werden akzeptiert. Ein eigener Ordner wird über seinen Slug oder seinen Namen referenziert.

  • Paginierung

    limit reicht von 1 bis 100 (Standard 25). Die Antwort enthält has_more und next_cursor: Senden Sie next_cursor beim nächsten Aufruf als cursor.

  • Stapelaktionen

    Aktionsbefehle akzeptieren ids (eine Liste mit bis zu 100) oder id (eine einzelne) und antworten pro Element mit items, ok_count und failed_count.

  • scope

    thread gilt für die gesamte Konversation im Quellordner. message gilt 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.

  • 400INVALID_JSON

    Der Body ist nicht {"commands":[...]} oder enthält mehr als 20 Befehle.

  • 401MISSING_AUTH_HEADER

    Es wurde kein Authorization-Header gesendet.

  • 401INVALID_TOKEN

    Der Token ist fehlerhaft, unbekannt oder widerrufen.

  • 401TOKEN_EXPIRED

    Der Access Token ist abgelaufen. Rufen Sie Refresh Token auf und wiederholen Sie die Anfrage.

  • 429RATE_LIMITED

    Mehr als 15 Anfragen/s oder 15 gleichzeitig laufende Anfragen für dieselbe IP + dasselbe Postfach. Warten Sie die in Retry-After angegebene Anzahl Sekunden.

  • 503AUTH_UNAVAILABLE

    Die Authentifizierung ist vorübergehend nicht verfügbar. Versuchen Sie es erneut.

  • CMDUNKNOWN_COMMAND

    Der Befehlsname existiert nicht.

  • CMDINVALID_ARGS

    Ein erforderliches Argument fehlt oder ist ungültig.

  • CMDREAD_ONLY_ACCESS

    Das Token oder die App hat Nur-lesen-Zugriff und der Befehl schreibt. Bei der Route zum Hochladen von Anhängen ist es HTTP 403.

  • CMDINTERNAL

    Serverfehler. Die Details werden nur ins Server-Log geschrieben.