Receber e-mails: Rotas

Run Commands

O ponto de entrada único para ler e gerenciar uma caixa de correio. Envie de 1 a 20 comandos em uma requisição e receba um resultado por comando.

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

Toda ação na caixa de correio (listar, ler, buscar, marcar, mover, enviar, responder…) é um comando enviado para esta rota. As páginas abaixo desta documentam cada comando e seus argumentos.

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 body

  • commandsobject[]obrigatório

    De 1 a 20 comandos, executados em ordem.

  • commands[].commandstringobrigatório

    O nome do comando, por exemplo list_threads.

  • 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. O 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',
  {
    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);
}

Resposta

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

Campos da resposta

  • type

    Sempre SUCCESS quando a requisição em si foi aceita.

  • 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[].data

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

  • results[].code

    O código do erro. Só aparece quando type é ERROR.

  • results[].message

    Uma mensagem de erro legível. Só aparece quando type é ERROR.

Autenticação

Toda rota de comandos precisa de um access token. O token decide qual caixa de correio é usada: nenhum argumento seleciona outro usuário.

  • Authorization

    Envie Authorization: <token> ou Authorization: Bearer <token>.

  • Formato do token

    S.C.G. seguido de 100 caracteres. Identifica o dono (usuário + remetente).

  • Validade

    Access tokens duram 1 hora. Quando um expira, você recebe TOKEN_EXPIRED: chame Refresh Token e repita a requisição.

!

O token resolvido fica em cache por até 1 hora, então um token revogado pode continuar funcionando até esse cache expirar.

Acesso somente leitura

Um token criado como Somente leitura, ou um app autorizado como Somente leitura, só consegue ler a caixa.

Comandos permitidos

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
!

Qualquer comando de escrita responde READ_ONLY_ACCESS (HTTP 403 na rota de upload de anexo).

i

No MCP, as tools de escrita não aparecem para uma conexão Somente leitura.

Use um resultado anterior com $ref

Qualquer valor dentro de args pode ser {"$ref": "<id>", "path": "<path>"}. Ele é substituído pelo valor encontrado em path no resultado do comando com esse id. Em path, * percorre uma lista e achata o resultado. Assim você lista e lê em uma única requisição.

Body da requisição

{
  "commands": [
    {
      "command": "list_threads",
      "args": {
        "limit": 5
      },
      "id": "a"
    },
    {
      "command": "get_messages",
      "args": {
        "ids": {
          "$ref": "a",
          "path": "threads/*/last_message_uid"
        }
      },
      "id": "b"
    }
  ]
}
  • $ref

    O id de um comando anterior na mesma requisição.

  • path

    Caminho separado por barras dentro desse resultado. * passa por cada item de uma lista.

Rate limits e cache

Os limites valem por IP + usuário + remetente. Não há fila: quando você passa do limite, a requisição é rejeitada com HTTP 429 e um header Retry-After.

  • 15 requisições / segundo

    Pico de 15. Respostas servidas pelo cache também contam.

  • 15 em andamento

    No máximo 15 requisições sendo processadas ao mesmo tempo.

  • Use lotes em vez de loops

    Envie até 20 comandos por requisição em vez de uma requisição por ação.

  • Cache de leitura: 1,5 s

    A mesma leitura (mesmo comando e args) dentro de 1,5 segundo retorna o mesmo resultado. Vale para list_folders, get_counters, list_threads, list_messages, get_thread, get_messages, search, get_trust e list_trust.

  • Deduplicação de escrita: 1,5 s

    A mesma escrita repetida dentro de 1,5 segundo roda só uma vez, então um polling que envia o mesmo reply duas vezes não envia dois e-mails.

  • Invalidação do cache

    Qualquer comando de escrita limpa na hora o cache de leitura daquela caixa de correio, então a próxima leitura já vê o novo estado.

i

E-mails entregues na caixa de correio, ou alterações feitas no webmail, aparecem nas leituras em até 1,5 segundo.

Convenções

Estas regras valem para todos os comandos.

  • Pastas do sistema

    INBOX, Sent, Archive, Trash, Drafts, Spam, Promotions e Snoozed. Aliases como inbox, archived, draft, junk e promotion são aceitos. Uma pasta personalizada é referenciada pelo slug ou pelo nome.

  • Paginação

    limit vai de 1 a 100 (padrão 25). A resposta tem has_more e next_cursor: envie next_cursor como cursor na próxima chamada.

  • Ações em lote

    Comandos de ação aceitam ids (uma lista de até 100) ou id (um só) e respondem item por item com items, ok_count e failed_count.

  • scope

    thread se aplica à conversa inteira na pasta de origem. message se aplica só ao id informado.

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 body não é {"commands":[...]} ou tem mais de 20 comandos.

  • 401MISSING_AUTH_HEADER

    Nenhum header Authorization foi enviado.

  • 401INVALID_TOKEN

    O token está malformado, é desconhecido ou foi revogado.

  • 401TOKEN_EXPIRED

    O access token expirou. Chame Refresh Token e repita a requisição.

  • 429RATE_LIMITED

    Mais de 15 requisições/s ou 15 em andamento para o mesmo IP + caixa de correio. Espere o número de segundos indicado em Retry-After.

  • 503AUTH_UNAVAILABLE

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

  • CMDUNKNOWN_COMMAND

    O nome do comando não existe.

  • CMDINVALID_ARGS

    Um argumento obrigatório está ausente ou é inválido.

  • CMDREAD_ONLY_ACCESS

    O token ou app tem acesso Somente leitura e o comando escreve. Na rota de upload de anexo, é HTTP 403.

  • CMDINTERNAL

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