Messaging REST API

Complete reference for all Messaging wire REST endpoints. All endpoints require authentication via JWT token.

Send Email

POST /messaging/email

curl -X POST http://localhost:3000/messaging/email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "to": "user@example.com",
    "subject": "Hello from FluxKit",
    "body": "<h1>Hello!</h1><p>This is a test email.</p>"
  }'

Field	Type	Required	Description
to	string | string[]	Yes	Recipient email(s)
subject	string	Yes	Email subject line
body	string	Yes	HTML email body
text	string	No	Plain text fallback
cc	string | string[]	No	CC recipients
bcc	string | string[]	No	BCC recipients
replyTo	string	No	Reply-to address

Response (200):

{
  "messageId": "abc123",
  "status": "sent",
  "channel": "email",
  "to": "user@example.com"
}

---

Send Email Template

POST /messaging/email/template

curl -X POST http://localhost:3000/messaging/email/template \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "to": "user@example.com",
    "template": "welcome",
    "data": {
      "name": "Alice",
      "appName": "My App"
    }
  }'

Response (200):

{
  "messageId": "abc123",
  "status": "sent",
  "channel": "email",
  "to": "user@example.com",
  "template": "welcome"
}

---

Send SMS

POST /messaging/sms

curl -X POST http://localhost:3000/messaging/sms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "to": "+1234567890",
    "body": "Your verification code is 482901"
  }'

Field	Type	Required	Description
to	string	Yes	Phone number (E.164)
body	string	Yes	Message text

Response (200):

{
  "messageId": "SM1234567890abcdef",
  "status": "sent",
  "channel": "sms",
  "to": "+1234567890"
}

---

Send WhatsApp

POST /messaging/whatsapp

curl -X POST http://localhost:3000/messaging/whatsapp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "to": "+1234567890",
    "body": "Your order has been shipped!"
  }'

Field	Type	Required	Description
to	string	Yes	Phone number (E.164)
body	string	Yes	Message text
media	object	No	Media attachment

Response (200):

{
  "messageId": "wamid.abc123",
  "status": "sent",
  "channel": "whatsapp",
  "to": "+1234567890"
}

---

Message Logs

GET /messaging/logs

Retrieve sent message logs with optional filters.

curl "http://localhost:3000/messaging/logs?channel=email&limit=20" \
  -H "Authorization: Bearer eyJhbGci..."

Param	Type	Default	Description
channel	string	all	Filter by channel
to	string	--	Filter by recipient
status	string	--	Filter by status
limit	number	20	Results per page
offset	number	0	Pagination offset

Response (200):

{
  "logs": [
    {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "channel": "email",
      "to": "user@example.com",
      "subject": "Hello",
      "status": "sent",
      "messageId": "abc123",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

---

Health

GET /messaging/health

Check messaging wire health and provider status.

curl http://localhost:3000/messaging/health

Response (200):

{
  "status": "healthy",
  "providers": {
    "email": { "provider": "smtp", "status": "connected" },
    "sms": { "provider": "twilio", "status": "connected" },
    "whatsapp": { "provider": "twilio", "status": "connected" }
  }
}

---

Error Responses

All messaging endpoints return errors in this format:

{
  "error": {
    "code": "SEND_FAILED",
    "message": "Failed to send email: connection refused",
    "details": {
      "channel": "email",
      "provider": "smtp"
    }
  }
}

Code	Status	Description
VALIDATION_ERROR	400	Invalid request body
UNAUTHORIZED	401	Missing or invalid token
PROVIDER_NOT_CONFIGURED	400	Provider not set up
SEND_FAILED	500	Provider delivery failure
RATE_LIMITED	429	Too many requests