SMS: Send

Send one or more SMS messages via the Mersal API.

3 min read

Send one or more SMS messages in a single request. Pass multiple entries in the contact array to do a bulk send, and optionally schedule each message for future delivery or target a specific gateway.

Endpoint

POSThttps://mersal.it/api/sms/send

Authentication

Requires your personal API key via the Api-key header (or the api_key query/body fallback). See Authentication.

Request parameters

Name	Type	Required	Description
`contact`	array	Yes	Array of recipients. Must contain at least 1 item.
`contact.*.number`	string	Yes	The recipient's phone number.
`contact.*.message`	string	Yes	The SMS message body.
`contact.*.gateway_identifier`	string	No	UID of a specific SMS gateway to send through. Omit to use your account's default/active SMS gateway. Pass a specific gateway's UID to force that gateway — for example, to route through the Android SIM Gateway instead of an SMS API provider.
`contact.*.schedule_at`	string	No	Schedule delivery for a future time, format `Y-m-d H:i:s`. Omit to send immediately.

Example request

curl -X POST https://mersal.it/api/sms/send \
  -H "Api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": [
      {
        "number": "+201234567890",
        "message": "Your order has shipped!"
      },
      {
        "number": "+201098765432",
        "message": "Reminder: your appointment is tomorrow at 10am.",
        "schedule_at": "2026-08-01 10:00:00"
      }
    ]
  }'

<?php
 
$response = Http::withHeaders([
    'Api-key' => 'YOUR_API_KEY',
    'Content-Type' => 'application/json',
])->post('https://mersal.it/api/sms/send', [
    'contact' => [
        [
            'number' => '+201234567890',
            'message' => 'Your order has shipped!',
        ],
        [
            'number' => '+201098765432',
            'message' => 'Reminder: your appointment is tomorrow at 10am.',
            'schedule_at' => '2026-08-01 10:00:00',
        ],
    ],
]);
 
$data = $response->json();

<?php
 
$payload = [
    'contact' => [
        [
            'number' => '+201234567890',
            'message' => 'Your order has shipped!',
        ],
    ],
];
 
$ch = curl_init('https://mersal.it/api/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Api-key: YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
 
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch("https://mersal.it/api/sms/send", {
  method: "POST",
  headers: {
    "Api-key": process.env.MERSAL_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact: [
      { number: "+201234567890", message: "Your order has shipped!" },
      {
        number: "+201098765432",
        message: "Reminder: your appointment is tomorrow at 10am.",
        schedule_at: "2026-08-01 10:00:00",
      },
    ],
  }),
});
 
const data = await response.json();

import os
import requests
 
response = requests.post(
    "https://mersal.it/api/sms/send",
    headers={"Api-key": os.environ["MERSAL_API_KEY"]},
    json={
        "contact": [
            {"number": "+201234567890", "message": "Your order has shipped!"},
            {
                "number": "+201098765432",
                "message": "Reminder: your appointment is tomorrow at 10am.",
                "schedule_at": "2026-08-01 10:00:00",
            },
        ]
    },
)
 
data = response.json()

Example response

{
  "success": true,
  "message": "SMS queued successfully",
  "data": {
    "contact": [
      {
        "number": "+201234567890",
        "status": "queued"
      },
      {
        "number": "+201098765432",
        "status": "scheduled"
      }
    ]
  }
}

On validation failure, Mersal returns 422:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "contact.0.number": ["The contact.0.number field is required."]
  }
}

Errors

Common failure modes are a missing/invalid API key, an expired subscription, or a 422 validation error on the contact array. See Errors and Status Codes for the full reference.

Authentication

WhatsApp: Send

Was this page helpful?