Communication Queue API - cURL Examples 🚀

Complete collection of cURL commands for testing and using the Communication Queue API.

🔧 Setup

Replace these placeholders in all commands:

<BUSINESS_ID>: Your business UUID
<JOB_ID>: Queue job UUID
<COMM_ID>: Communication UUID
<YOUR_TOKEN>: Your JWT authentication token

Base URL: http://localhost:3000/api (adjust for your environment)

📊 1. Get Queue Statistics

Essential for monitoring dashboards

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/stats" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json"

Expected Response:

{
  "total": 150,
  "pending": 45,
  "processing": 5,
  "completed": 90,
  "failed": 10,
  "cancelled": 0,
  "oldestPending": "2025-10-26T10:30:00Z",
  "avgProcessingTimeSeconds": 2.5
}

Use this for:

Dashboard widgets
Health checks
Monitoring alerts
Capacity planning

📋 2. List Pending Jobs

See what's waiting in the queue

Get first 10 pending jobs (default)

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/pending" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Get 50 pending jobs

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/pending?limit=50" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Pretty print with jq

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/pending?limit=20" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '.'

Use this for:

Queue backlog monitoring
Verify scheduled send times
Check job priorities
Debug queue delays

🚨 3. List Failed Jobs

Critical for operations - see what's broken

Get last 10 failed jobs (default)

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/failed" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Get last 100 failed jobs

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/failed?limit=100" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Extract error messages only

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/failed?limit=50" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '.[] | {id, lastError, attempts}'

Use this for:

Operations monitoring
Error pattern analysis
SLA tracking
Recovery planning

🔍 4. Get Specific Job Details

Inspect a single job in detail

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/<JOB_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Pretty formatted

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/<JOB_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '.'

Extract specific fields

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/<JOB_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '{status, attempts, lastError, scheduledAt}'

Use this for:

Debugging specific failures
Audit trail investigation
Performance analysis
Payload inspection

🔄 5. Retry Failed Job

Manually retry a failed or cancelled job

Basic retry

curl -X POST \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/<JOB_ID>/retry" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json"

With verbose output

curl -X POST \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/<JOB_ID>/retry" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -v

Expected Success Response:

{
  "success": true,
  "message": "Job successfully queued for retry",
  "job": {
    "id": "...",
    "status": "pending",
    "attempts": 0,
    "scheduledAt": "2025-10-26T11:30:00Z"
  }
}

Expected Error Response:

{
  "success": false,
  "message": "Job cannot be retried (current status: completed)"
}

Use this for:

Recovery after fixing issues
Transient error retry
Manual intervention
Operations triage

⛔ 6. Cancel Pending Job

Stop a scheduled job from being sent

curl -X POST \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/<JOB_ID>/cancel" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json"

Expected Response:

{
  "success": true,
  "message": "Job cancelled successfully",
  "job": {
    "id": "...",
    "status": "cancelled",
    "updatedAt": "2025-10-26T11:35:00Z"
  }
}

Use this for:

Stop wrong scheduled sends
Cancel before sending mistakes
Compliance (opted-out customers)
Emergency stops

🗑️ 7. Delete Job (Admin Only)

Permanently remove a job from the queue

curl -X DELETE \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/<JOB_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Expected Response:

HTTP 204 No Content
(Empty response body)

With status code check:

curl -X DELETE \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/<JOB_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -w "\nHTTP Status: %{http_code}\n"

⚠️ WARNING: Destructive operation! Cannot be undone.

Use this for:

Cleanup old failed jobs
Data retention compliance
Remove stuck/corrupted jobs
Database hygiene

📄 8. Get Jobs by Communication ID

See all queue attempts for a specific communication

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/by-communication/<COMM_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Show retry history

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/by-communication/<COMM_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '.[] | {status, attempts, scheduledAt, lastError}'

Use this for:

Retry history tracking
Debugging retry behavior
Audit trail
Performance analysis

⚡ 9. Trigger Manual Processing

Force immediate queue processing (admin only)

curl -X POST \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/process-now" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json"

Expected Response:

{
  "success": true,
  "message": "Queue processing completed"
}

⚠️ Note: Normally runs automatically every 30 seconds via cron.

Use this for:

Testing
Debugging
Emergency processing
Development

🔗 Complete Workflow Examples

Workflow 1: Monitor and Fix Failed Jobs

# Step 1: Check queue health
curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/stats" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '{pending, failed, processing}'

# Step 2: If failed > 0, get failed jobs
curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/failed?limit=50" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '.[] | {id, lastError, attempts}' > failed-jobs.json

# Step 3: Group by error type (manually analyze failed-jobs.json)
# Example: All failed with "SendGrid API error"

# Step 4: Fix the issue (e.g., update API key)

# Step 5: Retry failed jobs
for job_id in $(jq -r '.[] | .id' failed-jobs.json); do
  curl -X POST \
    "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/${job_id}/retry" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -H "Content-Type: application/json"
  echo "Retried job: $job_id"
  sleep 1
done

Workflow 2: Cancel Scheduled Campaign

# Step 1: Find pending jobs
curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/pending?limit=100" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  > pending-jobs.json

# Step 2: Filter by criteria (manually or with jq)
# Example: Find all jobs scheduled for next hour with specific payload pattern
cat pending-jobs.json | jq '.[] | select(.scheduledAt < "2025-10-26T12:00:00Z") | {id, scheduledAt}' \
  > jobs-to-cancel.json

# Step 3: Cancel filtered jobs
for job_id in $(jq -r '.id' jobs-to-cancel.json); do
  curl -X POST \
    "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/${job_id}/cancel" \
    -H "Authorization: Bearer <YOUR_TOKEN>" \
    -H "Content-Type: application/json"
  echo "Cancelled job: $job_id"
done

Workflow 3: Investigate Communication Delivery

# Customer reports: "Didn't receive invoice email"
# You have the communication ID

# Step 1: Get all queue attempts for this communication
curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/by-communication/<COMM_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '.'

# Step 2: Check each attempt
# - How many attempts were made?
# - What were the errors?
# - When did it finally succeed/fail?

# Step 3: If all failed, get details of last attempt
LAST_JOB_ID=$(curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/by-communication/<COMM_ID>" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq -r 'sort_by(.updatedAt) | last | .id')

curl -X GET \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/${LAST_JOB_ID}" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  | jq '.lastError'

# Step 4: Fix issue and retry
curl -X POST \
  "http://localhost:3000/api/businesses/<BUSINESS_ID>/communication-queue/${LAST_JOB_ID}/retry" \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json"

📊 Monitoring Scripts

Health Check Script

Save as check-queue-health.sh:

#!/bin/bash

BUSINESS_ID="your-business-id"
TOKEN="your-auth-token"
BASE_URL="http://localhost:3000/api"

# Get stats
STATS=$(curl -s -X GET \
  "${BASE_URL}/businesses/${BUSINESS_ID}/communication-queue/stats" \
  -H "Authorization: Bearer ${TOKEN}")

PENDING=$(echo $STATS | jq -r '.pending')
FAILED=$(echo $STATS | jq -r '.failed')
PROCESSING=$(echo $STATS | jq -r '.processing')

echo "=== Queue Health Check ==="
echo "Pending: $PENDING"
echo "Processing: $PROCESSING"
echo "Failed: $FAILED"

# Alert conditions
if [ "$PENDING" -gt 100 ]; then
  echo "⚠️  WARNING: High pending count ($PENDING)"
fi

if [ "$FAILED" -gt 10 ]; then
  echo "🚨 ALERT: High failure count ($FAILED)"
fi

if [ "$PROCESSING" -gt 20 ]; then
  echo "⚠️  WARNING: High processing count ($PROCESSING)"
fi

Bulk Retry Script

Save as retry-all-failed.sh:

#!/bin/bash

BUSINESS_ID="your-business-id"
TOKEN="your-auth-token"
BASE_URL="http://localhost:3000/api"

# Get all failed jobs
FAILED_JOBS=$(curl -s -X GET \
  "${BASE_URL}/businesses/${BUSINESS_ID}/communication-queue/failed?limit=100" \
  -H "Authorization: Bearer ${TOKEN}")

# Count
COUNT=$(echo $FAILED_JOBS | jq '. | length')
echo "Found $COUNT failed jobs"

# Confirm
read -p "Retry all $COUNT jobs? (y/n) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
  exit 0
fi

# Retry each
echo $FAILED_JOBS | jq -r '.[] | .id' | while read job_id; do
  echo "Retrying job: $job_id"
  
  RESULT=$(curl -s -X POST \
    "${BASE_URL}/businesses/${BUSINESS_ID}/communication-queue/${job_id}/retry" \
    -H "Authorization: Bearer ${TOKEN}" \
    -H "Content-Type: application/json")
  
  SUCCESS=$(echo $RESULT | jq -r '.success')
  
  if [ "$SUCCESS" = "true" ]; then
    echo "✅ Success"
  else
    echo "❌ Failed: $(echo $RESULT | jq -r '.message')"
  fi
  
  sleep 0.5  # Rate limiting
done

echo "Retry process complete!"

🎯 Quick Reference

Read Operations (Safe)

GET /stats                           # Queue statistics
GET /pending?limit=N                 # Pending jobs
GET /failed?limit=N                  # Failed jobs
GET /:id                            # Specific job
GET /by-communication/:commId       # Jobs for communication

Write Operations (Careful!)

POST /:id/retry                     # Retry failed job
POST /:id/cancel                    # Cancel pending job
POST /process-now                   # Trigger processing

Destructive Operations (Admin Only!)

DELETE /:id                         # Delete job permanently

🔐 Security Notes

Authentication Required: All endpoints require valid JWT token
Authorization: Some endpoints require admin role (DELETE, process-now)
Rate Limiting: Consider implementing rate limits for bulk operations
Audit Logging: All actions are logged server-side

🐛 Troubleshooting

Issue: 401 Unauthorized

# Check your token
curl -X GET "..." -H "Authorization: Bearer ${TOKEN}" -v
# Look for token expiration or invalid format

Issue: 404 Not Found

# Verify IDs are correct UUIDs
echo "Business ID: ${BUSINESS_ID}"
echo "Job ID: ${JOB_ID}"

Issue: Can't retry job

# Check job status first
curl -X GET \
  "http://localhost:3000/api/businesses/${BUSINESS_ID}/communication-queue/${JOB_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  | jq '.status'

# Only "failed" and "cancelled" jobs can be retried

📚 Additional Resources

Full API Documentation: COMMUNICATION-QUEUE-API.md
Implementation Details: COMMUNICATION-QUEUE-IMPROVEMENTS.md
System Design: multi-channel-communication-system-design.md

Happy Testing! 🚀

🔧 Setup​

📊 1. Get Queue Statistics​

📋 2. List Pending Jobs​

Get first 10 pending jobs (default)​

Get 50 pending jobs​

Pretty print with jq​

🚨 3. List Failed Jobs​

Get last 10 failed jobs (default)​

Get last 100 failed jobs​

Extract error messages only​

🔍 4. Get Specific Job Details​

Pretty formatted​

Extract specific fields​

🔄 5. Retry Failed Job​

Basic retry​

With verbose output​

⛔ 6. Cancel Pending Job​

🗑️ 7. Delete Job (Admin Only)​

📄 8. Get Jobs by Communication ID​

Show retry history​

⚡ 9. Trigger Manual Processing​

🔗 Complete Workflow Examples​

Workflow 1: Monitor and Fix Failed Jobs​

Workflow 2: Cancel Scheduled Campaign​

Workflow 3: Investigate Communication Delivery​

📊 Monitoring Scripts​

Health Check Script​

Bulk Retry Script​

🎯 Quick Reference​

Read Operations (Safe)​

Write Operations (Careful!)​

Destructive Operations (Admin Only!)​

🔐 Security Notes​

🐛 Troubleshooting​

Issue: 401 Unauthorized​

Issue: 404 Not Found​

Issue: Can't retry job​

📚 Additional Resources​

🔧 Setup

📊 1. Get Queue Statistics

📋 2. List Pending Jobs

Get first 10 pending jobs (default)

Get 50 pending jobs

Pretty print with jq

🚨 3. List Failed Jobs

Get last 10 failed jobs (default)

Get last 100 failed jobs

Extract error messages only

🔍 4. Get Specific Job Details

Pretty formatted

Extract specific fields

🔄 5. Retry Failed Job

Basic retry

With verbose output

⛔ 6. Cancel Pending Job

🗑️ 7. Delete Job (Admin Only)

📄 8. Get Jobs by Communication ID

Show retry history

⚡ 9. Trigger Manual Processing

🔗 Complete Workflow Examples

Workflow 1: Monitor and Fix Failed Jobs

Workflow 2: Cancel Scheduled Campaign

Workflow 3: Investigate Communication Delivery

📊 Monitoring Scripts

Health Check Script

Bulk Retry Script

🎯 Quick Reference

Read Operations (Safe)

Write Operations (Careful!)

Destructive Operations (Admin Only!)

🔐 Security Notes

🐛 Troubleshooting

Issue: 401 Unauthorized

Issue: 404 Not Found

Issue: Can't retry job

📚 Additional Resources