Senders: rotas

Run Commands

O ponto de entrada único para senders. Envie de 1 a 20 comandos em um request e receba um resultado por comando.

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

Mesmo envelope de Domains, Contacts e Logs. As páginas abaixo desta documentam cada comando.

i

Os erros são informados por comando. Um comando que falha não interrompe os outros, e o status HTTP continua 200.

Parâmetros do corpo

  • commandsobject[]obrigatório

    1 a 20 comandos, executados em ordem. O corpo inteiro pode ter até 1 MB.

  • commands[].commandstringobrigatório

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

  • commands[].argsobjectopcional

    Os argumentos do comando. Qualquer valor pode ser um $ref para o resultado de um comando anterior.

  • commands[].idstringopcional

    Seu próprio identificador para o resultado. Padrão: o índice ("0", "1"…). Obrigatório se você quiser usar $ref.

Início rápido

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

Resposta

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

Campos da resposta

  • type

    Sempre SUCCESS quando o request em si foi aceito.

  • results[].command

    O comando que gerou este resultado.

  • results[].id

    O id que você enviou, ou o índice do comando.

  • results[].type

    SUCCESS ou ERROR.

  • results[].took_ms

    Tempo que o comando levou dentro do servidor.

  • results[].data

    A saída do comando. Só presente quando type é SUCCESS.

  • results[].code / message

    O erro. Só presente quando type é ERROR.

Autenticação

Use a API key que você cria no dashboard, em Developers → API Keys, com os scopes de que os comandos precisam.

  • Authorization

    Envie Authorization: <api key> ou Authorization: Bearer <api key>.

  • sender:read

    list_senders e get_sender.

  • sender:create

    create_sender.

  • sender:update

    update_sender e update_sender_description.

  • sender:delete

    delete_sender.

  • Tokens de mailbox

    O token do webmail não funciona aqui. Ele é rejeitado com WRONG_CREDENTIAL_TYPE.

  • IPs permitidos

    Se a chave tiver uma lista de IPs permitidos, requests de outros IPs recebem 403 IP_NOT_ALLOWED.

Encadeando com $ref

Crie um sender e envie o id dele para o próximo comando no mesmo request.

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 / segundo

    Por IP + API key. Acima disso, HTTP 429 com um header Retry-After.

  • 15 simultâneos

    No máximo 15 requests sendo processados ao mesmo tempo, por IP + API key.

  • Por comando, por conta

    create_sender e update_sender 10/min · update_sender_description 20/min · delete_sender 30/min. Acima disso, o comando responde RATE_LIMITED.

  • Sem cache

    Toda chamada lê o banco de dados. O que você recebe é sempre atual.

Erros

Erros no nível HTTP retornam type, code e message. Erros marcados com CMD voltam dentro do resultado do comando, com HTTP 200.

  • 400INVALID_JSON

    O corpo não é {"commands":[...]} ou tem mais de 1 MB.

  • 400INVALID_ARGS

    O request não tem comandos ou tem mais de 20.

  • 401MISSING_AUTH_HEADER

    Nenhum header Authorization foi enviado.

  • 401INVALID_API_KEY

    A API key não existe, foi revogada ou foi desativada no dashboard.

  • 401API_KEY_EXPIRED

    A API key passou da data de expiração definida no dashboard.

  • 401WRONG_CREDENTIAL_TYPE

    Foi enviado um token de mailbox. A Senders API precisa de uma API key do dashboard.

  • 403IP_NOT_ALLOWED

    O request veio de um IP que não está nos IPs permitidos da chave.

  • 403ACCOUNT_BLOCKED

    A conta está bloqueada.

  • 403MISSING_SCOPE

    A chave não tem nenhum scope `sender:*`, então nenhum comando pode rodar.

  • 429RATE_LIMITED

    Mais de 15 requests/s ou 15 simultâneos para o mesmo IP + API key. Espere o número de segundos em Retry-After.

  • 503AUTH_UNAVAILABLE

    A autenticação está temporariamente indisponível. Tente de novo.

  • CMDUNKNOWN_COMMAND

    O nome do comando não existe.

  • CMDINTERNAL

    Erro no servidor. O detalhe só é gravado no log do servidor.