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.
https://g.sendcorex.com/v1Toda 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.
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órioDe 1 a 20 comandos, executados em ordem.
commands[].commandstringobrigatórioO nome do comando, por exemplo
list_threads.commands[].argsobjectopcionalOs argumentos do comando. Qualquer valor pode ser um
$refpara o resultado de um comando anterior.commands[].idstringopcionalSeu 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
typeSempre
SUCCESSquando a requisição em si foi aceita.results[].commandO comando que gerou este resultado.
results[].idO
idque você enviou, ou o índice do comando.results[].typeSUCCESSouERROR.results[].dataA saída do comando. Só aparece quando
typeéSUCCESS.results[].codeO código do erro. Só aparece quando
typeéERROR.results[].messageUma 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.
AuthorizationEnvie
Authorization: <token>ouAuthorization: Bearer <token>.Formato do tokenS.C.G.seguido de 100 caracteres. Identifica o dono (usuário + remetente).ValidadeAccess 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_unsubscribedQualquer comando de escrita responde READ_ONLY_ACCESS (HTTP 403 na rota de upload de anexo).
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"
}
]
}$refO
idde um comando anterior na mesma requisição.pathCaminho 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 / segundoPico de 15. Respostas servidas pelo cache também contam.
15 em andamentoNo máximo 15 requisições sendo processadas ao mesmo tempo.
Use lotes em vez de loopsEnvie até 20 comandos por requisição em vez de uma requisição por ação.
Cache de leitura: 1,5 sA 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_trustelist_trust.Deduplicação de escrita: 1,5 sA mesma escrita repetida dentro de 1,5 segundo roda só uma vez, então um polling que envia o mesmo
replyduas vezes não envia dois e-mails.Invalidação do cacheQualquer 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.
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 sistemaINBOX,Sent,Archive,Trash,Drafts,Spam,PromotionseSnoozed. Aliases comoinbox,archived,draft,junkepromotionsão aceitos. Uma pasta personalizada é referenciada pelo slug ou pelo nome.Paginaçãolimitvai de 1 a 100 (padrão 25). A resposta temhas_moreenext_cursor: envienext_cursorcomocursorna próxima chamada.Ações em loteComandos de ação aceitam
ids(uma lista de até 100) ouid(um só) e respondem item por item comitems,ok_countefailed_count.scopethreadse aplica à conversa inteira na pasta de origem.messagese 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.
- 400
INVALID_JSONO body não é {"commands":[...]} ou tem mais de 20 comandos.
- 401
MISSING_AUTH_HEADERNenhum header Authorization foi enviado.
- 401
INVALID_TOKENO token está malformado, é desconhecido ou foi revogado.
- 401
TOKEN_EXPIREDO access token expirou. Chame Refresh Token e repita a requisição.
- 429
RATE_LIMITEDMais 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.
- 503
AUTH_UNAVAILABLEA autenticação está temporariamente indisponível. Tente novamente.
- CMD
UNKNOWN_COMMANDO nome do comando não existe.
- CMD
INVALID_ARGSUm argumento obrigatório está ausente ou é inválido.
- CMD
READ_ONLY_ACCESSO token ou app tem acesso Somente leitura e o comando escreve. Na rota de upload de anexo, é HTTP 403.
- CMD
INTERNALErro no servidor. O detalhe só é gravado no log do servidor.