Skip to main content

Send Message

POST 
/api/messaging/send

Unified endpoint for sending single or bulk messages.

Automatically detects single vs bulk based on presence of bulk_settings.

SINGLE MESSAGE SEND​

Send a message to a single recipient.

Email Example:​

{
  "message_data": {
    "recipient": "customer@example.com",
    "subject": "Welcome to our service!",
    "content": "Thank you for signing up.",
    "html_content": "<h1>Welcome!</h1><p>Thank you for signing up.</p>",
    "sender_name": "Acme Support Team"
  },
  "message_type": "TRANSACTIONAL",
  "priority": "HIGH"
}

SMS Example:​

  {
    "sender_type": "sms",
    "sender_identifier": "825b8057-c85f-44a9-9e9f-6e7d7389ecfc",
    "message_data": {
      "recipient": "+1234567890",
      "content": "Your appointment is confirmed for tomorrow at 3 PM.",
      "contact_id": "11111111-0001-0001-0001-000000000001",
      "metadata": {
        "campaign_id": "spring_promo",
        "sent_by": "SMS Test"
      }
    }
}

Instagram DM Example:​

{
  "sender_type": "instagram_dm",
  "sender_identifier": "825b8057-c85f-44a9-9e9f-6e7d7389ecfc",
  "message_data": {
    "recipient": "1234567890123456",
    "content": "Thanks for reaching out! We'll get back to you soon.",
    "image_url": "https://example.com/promo.jpg",
    "contact_id": "11111111-0001-0001-0001-000000000001"
  },
  "message_type": "TRANSACTIONAL"
}

Single Message Response:​

{
  "success": true,
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "channel_used": "EMAIL",
  "provider_used": "sendgrid",
  "provider_message_id": "msg_abc123",
  "status": "SENT",
  "cost": 0.001,
  "sent_at": "2025-01-31T10:30:00Z"
}

BULK MESSAGE SEND​

Send messages to multiple recipients using targeting criteria.

Bulk with Direct Lead IDs:​

{
  "bulk_settings": {
    "lead_ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440003"
    ]
  },
  "message_data": {
    "recipient": "placeholder@example.com",
    "subject": "Special Offer - 50% Off!",
    "content": "Limited time offer just for you!",
    "sender_name": "Marketing Team"
  },
  "message_type": "MARKETING",
  "priority": "NORMAL"
}

Bulk with Search Keyword:​

{
  "bulk_settings": {
    "search_keyword": "enterprise customers"
  },
  "message_data": {
    "recipient": "+1234567890",
    "content": "Exclusive enterprise plan now available!"
  },
  "message_type": "MARKETING"
}

Bulk with Filters:​

{
  "bulk_settings": {
    "filters": {
      "conditions": [
        {
          "id": "group-1",
          "conditions": [
            {
              "id": "cond-1",
              "field": "first_name",
              "operator": "contains",
              "value": "st"
            },
            {
              "id": "1759891068581-u3gsnk8f7",
              "field": "tags",
              "operator": "contains",
              "value": ["Import 10/05/25"]
            }
          ]
        }
      ]
    }
  },
  "message_data": {
    "recipient": "placeholder@example.com",
    "subject": "VIP Notification",
    "content": "Important update for VIP customers"
  },
  "message_type": "NOTIFICATION",
  "priority": "3"
}

Bulk with Assignees:​

{
  "bulk_settings": {
    "assignees": ["user-uuid-1", "user-uuid-2"]
  },
  "message_data": {
    "recipient": "placeholder@example.com",
    "subject": "Team Update",
    "content": "Check your assigned leads"
  },
  "message_type": "NOTIFICATION"
}

Bulk Response:​

{
  "total_leads": 150,
  "messages_sent": 148,
  "messages_failed": 2,
  "success_rate": 98.67
}

Parameters​

  • message_data: Typed message content

    • EmailMessageData: recipient, subject, content, sender, sender_name (optional), html_content (optional)
    • SMSMessageData: recipient, content, sender, media_urls (optional)

  • bulk_settings (optional): If provided, triggers bulk send

    • lead_ids: List of lead UUIDs for direct targeting
    • filters: FilterRequest for complex conditions
    • search_keyword: Search across name, email, company, phone
    • assignees: Filter by assigned user IDs
    • Can combine multiple criteria

  • message_type: TRANSACTIONAL, MARKETING, or NOTIFICATION

  • priority: NORMAL, HIGH, or LOW

  • send_identifier: Optional Channel ID from channels table to use for sending (query param)

Response​

Single send: Returns MessageResponse with delivery details Bulk send: Returns statistics dict with total_leads, messages_sent, success_rate

Request​

Responses​

Successful Response