Sender: Routen

Run Commands

Der einzige Einstiegspunkt für Sender. Senden Sie 1 bis 20 Befehle in einem Request und erhalten Sie ein Ergebnis pro Befehl.

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

Gleiches Envelope wie Domains, Contacts und Logs. Die Seiten darunter dokumentieren jeden Befehl.

i

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

Body-Parameter

  • commandsobject[]erforderlich

    1 bis 20 Befehle, der Reihe nach ausgeführt. Der gesamte Body darf bis zu 1 MB groß sein.

  • commands[].commandstringerforderlich

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

  • commands[].argsobjectoptional

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

  • commands[].idstringoptional

    Ihre eigene Kennung für das Ergebnis. Standard ist der Index ("0", "1" …). Pflicht, wenn Sie $ref verwenden möchten.

Schnellstart

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);
}

Antwort

{
  "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"
      }
    }
  ]
}

Antwortfelder

  • type

    Immer SUCCESS, wenn der Request 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[].took_ms

    Zeit, die der Befehl im Server benötigt hat.

  • results[].data

    Die Ausgabe des Befehls. Nur vorhanden, wenn type SUCCESS ist.

  • results[].code / message

    Der Fehler. Nur vorhanden, wenn type ERROR ist.

Authentifizierung

Verwenden Sie den API Key, den Sie im Dashboard unter Developers → API Keys erstellen, mit den Scopes, die die Befehle brauchen.

  • Authorization

    Senden Sie Authorization: <api key> oder Authorization: Bearer <api key>.

  • sender:read

    list_senders und get_sender.

  • sender:create

    create_sender.

  • sender:update

    update_sender und update_sender_description.

  • sender:delete

    delete_sender.

  • Mailbox-Tokens

    Das Webmail-Token funktioniert hier nicht. Es wird mit WRONG_CREDENTIAL_TYPE abgelehnt.

  • Erlaubte IPs

    Hat der Schlüssel eine IP-Allowlist, erhalten Requests von anderen IPs 403 IP_NOT_ALLOWED.

Verketten mit $ref

Legen Sie einen Sender an und geben Sie seine ID an den nächsten Befehl im selben Request weiter.

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

    Pro IP + API Key. Darüber HTTP 429 mit einem Retry-After-Header.

  • 15 gleichzeitig

    Höchstens 15 Requests gleichzeitig in Bearbeitung, pro IP + API Key.

  • Pro Befehl, pro Konto

    create_sender und update_sender 10/min · update_sender_description 20/min · delete_sender 30/min. Darüber antwortet der Befehl mit RATE_LIMITED.

  • Kein Cache

    Jeder Aufruf liest die Datenbank. Was Sie erhalten, ist immer aktuell.

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 größer als 1 MB.

  • 400INVALID_ARGS

    Der Request enthält keine Befehle oder mehr als 20.

  • 401MISSING_AUTH_HEADER

    Es wurde kein Authorization-Header gesendet.

  • 401INVALID_API_KEY

    Der API Key existiert nicht, wurde widerrufen oder im Dashboard deaktiviert.

  • 401API_KEY_EXPIRED

    Der API Key hat das im Dashboard festgelegte Ablaufdatum überschritten.

  • 401WRONG_CREDENTIAL_TYPE

    Es wurde ein Mailbox-Token gesendet. Die Senders API braucht einen API Key aus dem Dashboard.

  • 403IP_NOT_ALLOWED

    Der Request kam von einer IP, die nicht zu den erlaubten IPs des Schlüssels gehört.

  • 403ACCOUNT_BLOCKED

    Das Konto ist gesperrt.

  • 403MISSING_SCOPE

    Der Schlüssel hat keinen `sender:*`-Scope, daher kann kein Befehl laufen.

  • 429RATE_LIMITED

    Mehr als 15 Requests/s oder 15 gleichzeitig für dieselbe IP + API Key. Warten Sie die Sekunden aus Retry-After ab.

  • 503AUTH_UNAVAILABLE

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

  • CMDUNKNOWN_COMMAND

    Der Befehlsname existiert nicht.

  • CMDINTERNAL

    Serverfehler. Details werden nur ins Server-Log geschrieben.