Menerima Email: Rute
Run Commands
Satu-satunya titik masuk untuk membaca dan mengelola kotak surat. Kirim 1 sampai 20 perintah dalam satu request dan dapatkan satu hasil per perintah.
https://g.sendcorex.com/v1Setiap tindakan pada kotak surat (menampilkan daftar, membaca, mencari, menandai, memindahkan, mengirim, membalas…) adalah perintah yang dikirim ke rute ini. Halaman di bawah halaman ini mendokumentasikan setiap perintah beserta argumennya.
Error dilaporkan per perintah. Perintah yang gagal tidak menghentikan perintah lain, dan status HTTP tetap 200.
Parameter body
commandsobject[]wajib1 sampai 20 perintah, dijalankan berurutan.
commands[].commandstringwajibNama perintah, misalnya
list_threads.commands[].argsobjectopsionalArgumen perintah. Nilai apa pun bisa berupa
$refke hasil perintah sebelumnya.commands[].idstringopsionalPengenal Anda sendiri untuk hasilnya. Default-nya adalah indeks (
"0","1"…). Wajib jika Anda ingin memakai$ref.
Mulai cepat
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);
}Respons
{
"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
}
}
}
}
]
}Field respons
typeSelalu
SUCCESSjika request itu sendiri diterima.results[].commandPerintah yang menghasilkan hasil ini.
results[].ididyang Anda kirim, atau indeks perintah.results[].typeSUCCESSatauERROR.results[].dataOutput perintah. Hanya ada jika
typebernilaiSUCCESS.results[].codeKode error. Hanya ada jika
typebernilaiERROR.results[].messagePesan error yang mudah dibaca. Hanya ada jika
typebernilaiERROR.
Autentikasi
Setiap rute perintah memerlukan access token. Token menentukan kotak surat mana yang dipakai: tidak ada argumen yang bisa memilih pengguna lain.
AuthorizationKirim
Authorization: <token>atauAuthorization: Bearer <token>.Format tokenS.C.G.diikuti 100 karakter. Ini mengidentifikasi pemilik (pengguna + pengirim).Masa berlakuAccess token berlaku 1 jam. Saat kedaluwarsa, Anda menerima
TOKEN_EXPIRED: panggil Refresh Token lalu ulangi request.
Token yang sudah diresolusi di-cache hingga 1 jam, jadi token yang dicabut bisa tetap berfungsi sampai cache tersebut kedaluwarsa.
Akses hanya baca
Token yang dibuat sebagai Hanya baca, atau aplikasi yang diotorisasi sebagai Hanya baca, hanya bisa membaca mailbox.
Perintah yang diizinkan
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_unsubscribedSetiap perintah tulis membalas READ_ONLY_ACCESS (HTTP 403 di rute unggah lampiran).
Di MCP, tool tulis tidak muncul untuk koneksi Hanya baca.
Gunakan hasil sebelumnya dengan $ref
Nilai apa pun di dalam args bisa berupa {"$ref": "<id>", "path": "<path>"}. Nilai itu diganti dengan nilai yang ditemukan di path pada hasil perintah dengan id tersebut. Di path, * menelusuri list dan meratakan hasilnya. Dengan begitu Anda bisa menampilkan daftar dan membaca dalam satu request.
Body request
{
"commands": [
{
"command": "list_threads",
"args": {
"limit": 5
},
"id": "a"
},
{
"command": "get_messages",
"args": {
"ids": {
"$ref": "a",
"path": "threads/*/last_message_uid"
}
},
"id": "b"
}
]
}$refiddari perintah sebelumnya dalam request yang sama.pathPath yang dipisahkan garis miring di dalam hasil tersebut.
*menelusuri setiap item dalam list.
Rate limit dan cache
Batas berlaku per IP + pengguna + pengirim. Tidak ada antrean: jika Anda melewatinya, request ditolak dengan HTTP 429 dan header Retry-After.
15 request / detikPuncak 15. Respons yang dilayani dari cache juga dihitung.
15 sedang diprosesPaling banyak 15 request diproses pada saat yang sama.
Gunakan batch, bukan loopKirim hingga 20 perintah per request, bukan satu request per tindakan.
Cache baca: 1,5 detikPembacaan yang sama (perintah dan args yang sama) dalam 1,5 detik mengembalikan hasil yang sama. Berlaku untuk
list_folders,get_counters,list_threads,list_messages,get_thread,get_messages,search,get_trust, danlist_trust.De-duplikasi tulis: 1,5 detikPenulisan yang sama yang diulang dalam 1,5 detik hanya dijalankan sekali, jadi polling yang mengirim
replyyang sama dua kali tidak mengirim dua email.Invalidasi cacheSetiap perintah tulis langsung menghapus cache baca kotak surat tersebut, jadi pembacaan berikutnya melihat status terbaru.
Email yang dikirim ke kotak surat, atau perubahan di webmail, muncul di pembacaan dalam 1,5 detik.
Konvensi
Aturan ini berlaku untuk semua perintah.
Folder sistemINBOX,Sent,Archive,Trash,Drafts,Spam,Promotions, danSnoozed. Alias sepertiinbox,archived,draft,junk, danpromotionditerima. Folder kustom dirujuk dengan slug atau namanya.Paginasilimitdari 1 sampai 100 (default 25). Respons berisihas_moredannext_cursor: kirimnext_cursorsebagaicursorpada panggilan berikutnya.Tindakan batchPerintah tindakan menerima
ids(list hingga 100) atauid(satu saja) dan menjawab per item denganitems,ok_count, danfailed_count.scopethreadberlaku untuk seluruh percakapan di folder asal.messagehanya berlaku untuk id yang diberikan.
Error
Error di level HTTP mengembalikan type, code, dan message. Error yang ditandai CMD dikembalikan di dalam hasil perintah, dengan HTTP 200.
- 400
INVALID_JSONBody bukan {"commands":[...]} atau berisi lebih dari 20 perintah.
- 401
MISSING_AUTH_HEADERTidak ada header Authorization yang dikirim.
- 401
INVALID_TOKENToken salah format, tidak dikenal, atau dicabut.
- 401
TOKEN_EXPIREDAccess token sudah kedaluwarsa. Panggil Refresh Token lalu ulangi request.
- 429
RATE_LIMITEDLebih dari 15 request/detik atau 15 yang sedang diproses untuk IP + kotak surat yang sama. Tunggu sesuai jumlah detik di Retry-After.
- 503
AUTH_UNAVAILABLEAutentikasi sementara tidak tersedia. Coba lagi.
- CMD
UNKNOWN_COMMANDNama perintah tidak ada.
- CMD
INVALID_ARGSArgumen wajib tidak ada atau tidak valid.
- CMD
READ_ONLY_ACCESSToken atau aplikasi memiliki akses Hanya baca dan perintahnya menulis. Di rute unggah lampiran, ini HTTP 403.
- CMD
INTERNALError server. Detailnya hanya ditulis ke log server.