logicspike/docs

Communication

API Specification: Communication Service (Production Grade)

Base URL

  • Internal: http://communication-service (Service Binding)
  • Public: https://api.logicspike.com/v1/communication (Protected by Tenant API Key)

Authentication

  1. Service Binding: c.env.COMMUNICATION (No Auth required, internal only).
  2. Bearer Token: Authorization: Bearer <sk_live_...> (For external calls).

1. Delivery Endpoints (The "Pipe")

Quick Send (Unified)

POST /v1/send Sends a single message via any channel.

Request Body:

{
  "channel": "email", // email | sms | push | webhook
  "to": "user@example.com",
  "subject": "Welcome!", // Required for email
  "content": {
    "html": "<h1>Hi!</h1>",
    "text": "Hi!",
    "templateId": "welcome-v1",
    "variables": { "name": "Dipanshu" }
  },
  "priority": "normal", // high | normal | low
  "idempotencyKey": "signup_123", // Prevent duplicates
  "tenantId": "workspace_123" // Optional (inferred from Auth)
}

Response (200 OK):

{
  "id": "msg_01HQ...",
  "status": "queued",
  "provider": "resend-prod"
}

Batch Send (Bulk)

POST /v1/batch High-throughput ingestion for Newsletters/Campaigns.

Request Body:

{
  "channel": "email",
  "items": [
    { "to": "a@test.com", "content": { "variables": {"name": "A"} } },
    { "to": "b@test.com", "content": { "variables": {"name": "B"} } }
  ],
  "common": {
    "subject": "Weekly Newsletter",
    "content": { "templateId": "newsletter-week-42" },
    "priority": "low"
  }
}

2. Provider Management (The "Control Panel")

Create Provider

POST /v1/providers Securely stores credentials.

Request Body:

{
  "type": "twilio",
  "name": "My Twilio",
  "config": {
    "accountSid": "AC...",
    "authToken": "..." 
  },
  "enabled": true
}

Note: config is encrypted immediately upon receipt.

List Providers

GET /v1/providers Returns redacted config.

Response:

[
  {
    "id": "prov_123",
    "type": "twilio",
    "name": "My Twilio",
    "mask": "AC...7e91" // Never returns full secrets
  }
]

3. Webhooks (Inbound)

Status Callback

POST /v1/webhooks/:providerId Receives events from Twilio/Resend.

Payload: Provider-specific JSON. Action: Normalizes to MessageEvent and updates Message status.

Error Codes

  • 400 Bad Request: Validation failed (missing to).
  • 402 Payment Required: Tenant has no credits/provider configured.
  • 429 Too Many Requests: Rate limit per tenant.
  • 409 Conflict: Idempotency Key collision.
Communication