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.

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

Setiap 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.

i

Error dilaporkan per perintah. Perintah yang gagal tidak menghentikan perintah lain, dan status HTTP tetap 200.

Parameter body

  • commandsobject[]wajib

    1 sampai 20 perintah, dijalankan berurutan.

  • commands[].commandstringwajib

    Nama perintah, misalnya list_threads.

  • commands[].argsobjectopsional

    Argumen perintah. Nilai apa pun bisa berupa $ref ke hasil perintah sebelumnya.

  • commands[].idstringopsional

    Pengenal 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

  • type

    Selalu SUCCESS jika request itu sendiri diterima.

  • results[].command

    Perintah yang menghasilkan hasil ini.

  • results[].id

    id yang Anda kirim, atau indeks perintah.

  • results[].type

    SUCCESS atau ERROR.

  • results[].data

    Output perintah. Hanya ada jika type bernilai SUCCESS.

  • results[].code

    Kode error. Hanya ada jika type bernilai ERROR.

  • results[].message

    Pesan error yang mudah dibaca. Hanya ada jika type bernilai ERROR.

Autentikasi

Setiap rute perintah memerlukan access token. Token menentukan kotak surat mana yang dipakai: tidak ada argumen yang bisa memilih pengguna lain.

  • Authorization

    Kirim Authorization: <token> atau Authorization: Bearer <token>.

  • Format token

    S.C.G. diikuti 100 karakter. Ini mengidentifikasi pemilik (pengguna + pengirim).

  • Masa berlaku

    Access 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_unsubscribed
!

Setiap perintah tulis membalas READ_ONLY_ACCESS (HTTP 403 di rute unggah lampiran).

i

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"
    }
  ]
}
  • $ref

    id dari perintah sebelumnya dalam request yang sama.

  • path

    Path 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 / detik

    Puncak 15. Respons yang dilayani dari cache juga dihitung.

  • 15 sedang diproses

    Paling banyak 15 request diproses pada saat yang sama.

  • Gunakan batch, bukan loop

    Kirim hingga 20 perintah per request, bukan satu request per tindakan.

  • Cache baca: 1,5 detik

    Pembacaan 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, dan list_trust.

  • De-duplikasi tulis: 1,5 detik

    Penulisan yang sama yang diulang dalam 1,5 detik hanya dijalankan sekali, jadi polling yang mengirim reply yang sama dua kali tidak mengirim dua email.

  • Invalidasi cache

    Setiap perintah tulis langsung menghapus cache baca kotak surat tersebut, jadi pembacaan berikutnya melihat status terbaru.

i

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 sistem

    INBOX, Sent, Archive, Trash, Drafts, Spam, Promotions, dan Snoozed. Alias seperti inbox, archived, draft, junk, dan promotion diterima. Folder kustom dirujuk dengan slug atau namanya.

  • Paginasi

    limit dari 1 sampai 100 (default 25). Respons berisi has_more dan next_cursor: kirim next_cursor sebagai cursor pada panggilan berikutnya.

  • Tindakan batch

    Perintah tindakan menerima ids (list hingga 100) atau id (satu saja) dan menjawab per item dengan items, ok_count, dan failed_count.

  • scope

    thread berlaku untuk seluruh percakapan di folder asal. message hanya 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.

  • 400INVALID_JSON

    Body bukan {"commands":[...]} atau berisi lebih dari 20 perintah.

  • 401MISSING_AUTH_HEADER

    Tidak ada header Authorization yang dikirim.

  • 401INVALID_TOKEN

    Token salah format, tidak dikenal, atau dicabut.

  • 401TOKEN_EXPIRED

    Access token sudah kedaluwarsa. Panggil Refresh Token lalu ulangi request.

  • 429RATE_LIMITED

    Lebih dari 15 request/detik atau 15 yang sedang diproses untuk IP + kotak surat yang sama. Tunggu sesuai jumlah detik di Retry-After.

  • 503AUTH_UNAVAILABLE

    Autentikasi sementara tidak tersedia. Coba lagi.

  • CMDUNKNOWN_COMMAND

    Nama perintah tidak ada.

  • CMDINVALID_ARGS

    Argumen wajib tidak ada atau tidak valid.

  • CMDREAD_ONLY_ACCESS

    Token atau aplikasi memiliki akses Hanya baca dan perintahnya menulis. Di rute unggah lampiran, ini HTTP 403.

  • CMDINTERNAL

    Error server. Detailnya hanya ditulis ke log server.