SocialMate Local API

Smart queue

Inspect and drive the Smart Message Queue: items, batches, import, retry, pause/resume.

The Smart Message Queue paces outbound work through anti-ban for you. Inspecting it is free; writing to it (enqueue, import, retry, pause) is Pro (scheduledMessages). Every queued item still flows through the full anti-ban pipeline — there is no bypass — and is tagged source: "api" so you can tell API-initiated work apart in the live feed and queue.* webhooks.

Order of delivery. Items drain by priority ascending — 0 is most urgent, 3 is lowest (default 2); ties break oldest-first, and scheduled items wait for their time. So a priority: 0 OTP always jumps ahead of a priority: 3 newsletter. If the engine holds a send because risk is high, the account auto-cools and the queue resumes by itself the moment your risk score recovers — no fixed wait, no manual resume.

Inspect the queue

GET /v1/queue/status

scope: readFree

Aggregate counters (pending / processing / failed), per account.

curl http://localhost:3456/v1/queue/status \
  -H "x-api-key: YOUR_KEY"

{ "data": { "totalPending": 12, "totalProcessing": 1, "totalSentToday": 340, "totalFailedToday": 2, "activeBatches": 1, "globalPaused": false, "licensePaused": false, "perAccount": [ { "accountId": "a1b2c3", "pending": 12, "paused": false } ], "recentBatches": [] } }

licensePaused is true on Free (and after a Pro→Free downgrade) — the queue worker stops draining until you upgrade; it's distinct from globalPaused (a manual pause).

GET /v1/queue/items

scope: readFree

List items. Query params: accountId, batchId, status (CSV of pending/processing/sent/delivered/failed/cancelled), priority (CSV 0–3), search, limit (max 500), offset, sort (next_up default, newest, oldest).

curl "http://localhost:3456/v1/queue/items?status=pending,failed&sort=next_up&limit=50" \
  -H "x-api-key: YOUR_KEY"

{ "data": { "items": [ { "id": "5f3a9c2b8d1e4f6a7c0b2d9e", "accountId": "a1b2c3", "chatId": "[email protected]", "content": "Hi {{name}}", "status": "pending", "priority": 2, "scheduledAt": null } ], "total": 1, "hasMore": false } }

Note the shape: the queue endpoints return items / total / hasMore inside data — not a bare array with a separate pagination block like the contacts/messages/media lists. Page with limit + offset and stop when hasMore is false.

GET /v1/queue/batches

scope: readFree

List batches. Query params: accountId, status (active|completed|cancelled|paused), limit.

curl "http://localhost:3456/v1/queue/batches?status=active&limit=20" \
  -H "x-api-key: YOUR_KEY"

{ "data": [ { "id": "7c0b2d9e5f3a9c2b8d1e4f6a", "name": "June promo", "accountId": "a1b2c3", "status": "active", "totalCount": 500, "sentCount": 120, "failedCount": 1, "pendingCount": 379 } ] }

Drive the queue (Pro)

POST /v1/accounts/{id}/queue/items

scope: sendPro

Enqueue a single message (optionally scheduled). Body: chatId, content (required), displayName, priority (0–3, default 2), scheduledAt (unix-ms or null), maxRetries (0–10, default 3).

curl -X POST http://localhost:3456/v1/accounts/ACCOUNT_ID/queue/items \
  -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "chatId": "15559876543", "content": "Reminder: your appointment is tomorrow", "scheduledAt": 1718900000000 }'

{ "data": { "success": true, "item": { "id": "q_8f2…", "status": "pending" } } }

POST /v1/accounts/{id}/queue/import

scope: sendPro

Batch send (opt-in, off by default) — queue one batch of personalised messages, up to 5,000, from a template. One individual message per person, each paced by the anti-ban engine; identical text to many contacts is blocked by the duplicate-content guard, so personalise every row. Only for contacts who opted in — a Pro, consent-gated opt-in that returns 403 until you enable batch sending in the app. Body: template (with {{field}} placeholders), batchName, rows (1–5000, each { chatId, displayName?, fields? }), plus optional priority, scheduledAt, maxRetries.

curl -X POST http://localhost:3456/v1/accounts/ACCOUNT_ID/queue/import \
  -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{
        "template": "Hi {{name}}, your order {{order}} shipped 📦",
        "batchName": "Shipping June",
        "rows": [
          { "chatId": "15551234567", "fields": { "name": "Jane", "order": "#1024" } }
        ]
      }'

{ "data": { "success": true, "batch": { "id": "b_77…" }, "itemCount": 1 } }

POST /v1/queue/items/{itemId}/retry

scope: adminPro

Re-queue a failed item.

curl -X POST http://localhost:3456/v1/queue/items/q_1/retry \
  -H "x-api-key: ADMIN_KEY"

{ "data": { "success": true, "item": { "id": "q_1", "status": "pending" } } }

DELETE /v1/queue/items/{itemId}

scope: adminPro

Cancel a pending item.

curl -X DELETE http://localhost:3456/v1/queue/items/q_1 \
  -H "x-api-key: ADMIN_KEY"

{ "data": { "success": true, "item": { "id": "q_1", "status": "cancelled" } } }

POST /v1/queue/batches/{batchId}/retry · DELETE /v1/queue/batches/{batchId}

scope: adminPro

Retry all failed items in a batch, or cancel the whole batch.

curl -X POST http://localhost:3456/v1/queue/batches/batch_1/retry \
  -H "x-api-key: ADMIN_KEY"

{ "data": { "success": true, "retried": 12 } }

curl -X DELETE http://localhost:3456/v1/queue/batches/batch_1 \
  -H "x-api-key: ADMIN_KEY"

{ "data": { "success": true, "cancelled": 380 } }

POST /v1/queue/pause · /v1/queue/resume

scope: adminPro

Pause or resume the worker globally, or for one account with an optional accountId body field.

curl -X POST http://localhost:3456/v1/queue/pause \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "accountId": "ACCOUNT_ID" }'

{ "data": { "success": true, "paused": true, "accountId": "a1b2c3" } }

curl -X POST http://localhost:3456/v1/queue/resume \
  -H "x-api-key: ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{ "accountId": "ACCOUNT_ID" }'

{ "data": { "success": true, "paused": false, "accountId": "a1b2c3" } }