Skip to main content

Sending SMS

Send personalized SMS messages using your templates and configured SMS providers.

Single SMS Sending​

Send an SMS to a single recipient:

POST /sms/send
Content-Type: application/json
x-api-key: {your-api-key}

{
  "templateId": "sms-template-uuid",
  "to": "+1234567890",
  "variables": {
    "firstName": "John",
    "code": "123456",
    "appName": "MyApp"
  }
}

Response:

{
  "message": "SMS sent successfully",
  "messageId": "msg-id"
}

Bulk SMS Sending​

Send the same SMS to multiple recipients:

POST /sms/send-bulk
Content-Type: application/json
x-api-key: {your-api-key}

{
  "templateId": "sms-template-uuid",
  "recipients": [
    "+1234567890",
    "+1234567891",
  ],
  "variables": {
    "eventName": "Flash Sale",
    "discount": "50%",
    "expiryTime": "6 PM today"
  }
}

Response:

{
  "message": "Bulk sms processed: 2 sent, 0 failed",
  "success": true,
  "results": [
    {
      "recepient": "+1234567890",
      "success": true,
      "messageId": "sms-id-1",
      "provider": "provider-used",
      "deliveryLogId": "delivery-log-uuid"
    },
    {
      "recepient": "+1234567891",
      "success": true,
      "messageId": "sms-id-2",
      "provider": "provider-used",
      "deliveryLogId": "delivery-log-uuid"
    }
  ]
}

Phone Number Format​

  • Always include country code (e.g., +234 for Nigeria, +1 for US, +44 for UK)
  • Use international format: +[country code][phone number]
  • Remove spaces, dashes or special characters

Required Fields​

  • templateId: UUID of the SMS template to use
  • to/recipients: Phone number(s) in international format
  • variables: Object containing template variables

Error Handling​

Template Not Found​

{
  "error": "SMS template not found",
  "statusCode": 404
}

Invalid Phone Number​

{
  "error": "Invalid phone number format",
  "statusCode": 400
}

Provider Failure​

{
  "message": "All providers failed: provider specific error",
  "error": "Internal Server Error",
  "statusCode": 500
}

SMS Delivery Considerations​

  • SMS delivery times vary by provider and region
  • International SMS may have higher costs
  • Some countries have restrictions on SMS content
  • MessagePipe handles provider failover automatically