LaraCopilot’s SMS gateway API lets you configure outbound messaging providers, send SMS messages, and inspect delivery history — all in a single resource. Each gateway holds its own connection credentials and sender identity, and every message sent through the API is recorded as an SmsMessage record that tracks status from queued through to delivered.
All SMS gateway endpoints require an active admin session. Requests without a valid session cookie return 401 Unauthorized.
List SMS gateways Retrieve all configured SMS gateways. Pass search to filter by name, host, or provider type. Each result includes a messages_count field with the number of messages sent through that gateway.
Query parameters Filter gateways by name, server_host, or provider_type. Matches partial strings.
Response Human-readable status. Always "SMS gateways fetched successfully." on success.
Array of SMS gateway objects. Show Gateway object properties
Unique gateway identifier.
Display name for this gateway.
Gateway provider identifier (e.g. "jasmin", "smpp").
Hostname or IP address of the gateway server.
TCP port the gateway listens on.
Path appended to the host and port to form the send URL.
Authentication username for the gateway.
Default originating address shown to recipients.
Token used to validate inbound DLR callbacks from the gateway.
Whether this gateway is enabled for sending.
Whether to connect to the gateway over HTTPS.
Free-text notes for internal reference.
Arbitrary key-value metadata stored alongside the gateway.
Total number of messages sent through this gateway.
ISO 8601 timestamp when the gateway was created.
ISO 8601 timestamp of the last update.
curl https://your-instance.laracopilot.com/api/sms-gateways \ -b cookies.txt
curl "https://your-instance.laracopilot.com/api/sms-gateways?search=jasmin" \ -b cookies.txt
{ "message" : "SMS gateways fetched successfully." , "data" : [ { "id" : 1 , "name" : "Jasmin Primary" , "provider_type" : "jasmin" , "server_host" : "sms.example.com" , "server_port" : 8080 , "api_path" : "send" , "username" : "admin" , "default_sender_id" : "LaraCopilot" , "callback_token" : "tok_abc123" , "is_active" : true , "use_ssl" : false , "notes" : null , "meta" : null , "messages_count" : 142 , "created_at" : "2024-01-15T10:00:00.000000Z" , "updated_at" : "2024-03-01T14:22:10.000000Z" } ] }
Create a gateway Register a new SMS gateway. The password field is stored and used for Basic Auth when dispatching messages.
Request body Display name for this gateway. Maximum 255 characters.
Gateway provider identifier. Maximum 100 characters (e.g. "jasmin", "smpp").
Hostname or IP address of the gateway server. Maximum 255 characters.
TCP port the gateway listens on. Minimum value: 1.
Path segment appended after the host and port when building the send URL. Defaults to send when omitted. Maximum 255 characters.
Authentication username for Basic Auth. Maximum 255 characters.
Authentication password for Basic Auth. Maximum 255 characters.
Default originating address (alphanumeric sender ID or phone number). Maximum 30 characters.
Token included in DLR callback validation. Maximum 255 characters. See Webhooks for security guidance. Set to true to enable this gateway for outbound sending.
Set to true to connect to the gateway over HTTPS.
Free-text internal notes. No length limit enforced by the API.
Arbitrary key-value object for custom metadata. Stored as JSON.
Response Returns the newly created gateway object at HTTP 201.
curl -X POST https://your-instance.laracopilot.com/api/sms-gateways \ -b cookies.txt \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "Jasmin Primary", "provider_type": "jasmin", "server_host": "sms.example.com", "server_port": 8080, "api_path": "send", "username": "admin", "password": "s3cur3p4ss", "default_sender_id": "LaraCopilot", "callback_token": "tok_abc123", "is_active": true, "use_ssl": false }'
{ "message" : "SMS gateway created successfully." , "data" : { "id" : 1 , "name" : "Jasmin Primary" , "provider_type" : "jasmin" , "server_host" : "sms.example.com" , "server_port" : 8080 , "api_path" : "send" , "username" : "admin" , "default_sender_id" : "LaraCopilot" , "callback_token" : "tok_abc123" , "is_active" : true , "use_ssl" : false , "notes" : null , "meta" : null , "created_at" : "2024-03-20T09:15:00.000000Z" , "updated_at" : "2024-03-20T09:15:00.000000Z" } }
Get a gateway Fetch a single gateway by ID. The response includes messages_count.
GET /api/sms-gateways/{smsGateway}
Path parameters The ID of the SMS gateway to retrieve.
curl https://your-instance.laracopilot.com/api/sms-gateways/1 \ -b cookies.txt
{ "message" : "SMS gateway loaded successfully." , "data" : { "id" : 1 , "name" : "Jasmin Primary" , "provider_type" : "jasmin" , "server_host" : "sms.example.com" , "server_port" : 8080 , "api_path" : "send" , "username" : "admin" , "default_sender_id" : "LaraCopilot" , "callback_token" : "tok_abc123" , "is_active" : true , "use_ssl" : false , "notes" : null , "meta" : null , "messages_count" : 142 , "created_at" : "2024-01-15T10:00:00.000000Z" , "updated_at" : "2024-03-01T14:22:10.000000Z" } }
Update a gateway Replace all fields on an existing gateway. Every required field from Create a gateway must be included. Use PATCH /api/sms-gateways/{smsGateway} for partial updates with the same field rules.
PUT /api/sms-gateways/{smsGateway}
Path parameters The ID of the SMS gateway to update.
Request body Accepts the same fields as Create a gateway . All required fields must be present.
curl -X PUT https://your-instance.laracopilot.com/api/sms-gateways/1 \ -b cookies.txt \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "name": "Jasmin Primary (updated)", "provider_type": "jasmin", "server_host": "sms2.example.com", "server_port": 8080, "username": "admin", "password": "n3wp4ss", "is_active": true, "use_ssl": true }'
{ "message" : "SMS gateway updated successfully." , "data" : { "id" : 1 , "name" : "Jasmin Primary (updated)" , "provider_type" : "jasmin" , "server_host" : "sms2.example.com" , "server_port" : 8080 , "api_path" : null , "username" : "admin" , "default_sender_id" : "LaraCopilot" , "callback_token" : "tok_abc123" , "is_active" : true , "use_ssl" : true , "notes" : null , "meta" : null , "created_at" : "2024-01-15T10:00:00.000000Z" , "updated_at" : "2024-03-20T11:45:00.000000Z" } }
Delete a gateway Permanently delete a gateway. This action cannot be undone. Associated SmsMessage records are not automatically removed.
DELETE /api/sms-gateways/{smsGateway}
Path parameters The ID of the SMS gateway to delete.
curl -X DELETE https://your-instance.laracopilot.com/api/sms-gateways/1 \ -b cookies.txt
{ "message" : "SMS gateway deleted successfully." }
List messages for a gateway Return all SmsMessage records associated with a gateway, ordered newest first. Use this to inspect delivery history for a specific gateway.
GET /api/sms-gateways/{smsGateway}/messages
Path parameters The ID of the SMS gateway whose messages you want to list.
Response Always "SMS messages fetched successfully." on success.
Array of SMS message objects ordered by created_at descending. Show Message object properties
Unique message identifier.
ID of the gateway that handled this message.
Tenant that originated the message, or null for platform-level sends.
Destination phone number.
Originating address used for this message.
Message ID returned by the gateway, or a generated UUID if the gateway did not return one.
Current delivery status: queued, submitted, delivered, or failed.
Always "outbound" for messages sent via this API.
URL the gateway will POST the DLR to.
Raw JSON response body returned by the gateway, merged with subsequent DLR payloads.
Error detail when delivery_status is failed, otherwise null.
ISO 8601 timestamp when the send request was received.
ISO 8601 timestamp when the gateway accepted the message.
ISO 8601 timestamp when the DLR confirmed delivery.
curl https://your-instance.laracopilot.com/api/sms-gateways/1/messages \ -b cookies.txt
{ "message" : "SMS messages fetched successfully." , "data" : [ { "id" : 57 , "sms_gateway_id" : 1 , "tenant_id" : 4 , "to_number" : "+447911123456" , "from_sender" : "LaraCopilot" , "message" : "Your verification code is 849201." , "external_message_id" : "gw-msg-00992" , "delivery_status" : "delivered" , "direction" : "outbound" , "callback_url" : "https://your-instance.laracopilot.com/api/sms-gateways/1/dlr" , "remote_response" : { "message_id" : "gw-msg-00992" , "status" : 0 }, "error_message" : null , "requested_at" : "2024-03-20T10:00:00.000000Z" , "submitted_at" : "2024-03-20T10:00:01.000000Z" , "delivered_at" : "2024-03-20T10:00:08.000000Z" } ] }
Send an SMS Dispatch an outbound SMS through the specified gateway. LaraCopilot creates an SmsMessage record with delivery_status: "queued", forwards the message to the gateway over HTTP(S) with Basic Auth, then updates the record to submitted or failed based on the gateway’s response. The final SmsMessage object — with its current delivery_status — is returned synchronously.
POST /api/sms-gateways/{smsGateway}/send
Path parameters The ID of the SMS gateway to send through.
Request body Destination phone number in E.164 format (e.g. "+447911123456"). Maximum 30 characters.
Originating address shown to the recipient — alphanumeric sender ID or E.164 phone number. Maximum 30 characters.
SMS body text. Maximum 1000 characters.
ID of the tenant on whose behalf the message is sent. Stored on the SmsMessage record for attribution. Optional.
URL where the gateway should POST delivery receipts. Must be a valid URL. Defaults to https://your-instance.laracopilot.com/api/sms-gateways/{id}/dlr when omitted.
Send flow
Record created
An SmsMessage record is created with delivery_status: "queued" and requested_at set to the current time.
Dispatch to gateway
LaraCopilot POSTs to {scheme}://{server_host}:{server_port}/{api_path} using Basic Auth credentials from the gateway. The payload includes to, from, content, dlr-url, dlr-level, and dlr-method.
Status updated
On a successful gateway response the record is updated to delivery_status: "submitted" and submitted_at is set. On any HTTP error or network exception the status is set to "failed" and error_message is populated.
Response Always "SMS request processed.".
The SmsMessage record after the gateway interaction. Show Message object properties
Unique message identifier.
Gateway that handled this message.
Tenant attribution, or null.
Destination phone number.
Originating address used.
Message ID from the gateway response (message_id or id field), or a generated UUID.
"submitted" if the gateway accepted the request, "failed" if the gateway returned an error or the request timed out.
DLR callback URL sent to the gateway.
Parsed JSON body from the gateway response, or {"body": "<raw text>"} if the response was not valid JSON.
Error detail when delivery_status is "failed", otherwise null.
ISO 8601 timestamp when the send was initiated.
ISO 8601 timestamp when the gateway accepted the message, or null on failure.
ISO 8601 timestamp populated by the DLR webhook after delivery confirmation. null at this stage.
curl -X POST https://your-instance.laracopilot.com/api/sms-gateways/1/send \ -b cookies.txt \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "to_number": "+447911123456", "from_sender": "LaraCopilot", "message": "Your verification code is 849201.", "tenant_id": 4, "callback_url": "https://your-instance.laracopilot.com/api/sms-gateways/1/dlr" }'
{ "message" : "SMS request processed." , "data" : { "id" : 58 , "sms_gateway_id" : 1 , "tenant_id" : 4 , "to_number" : "+447911123456" , "from_sender" : "LaraCopilot" , "message" : "Your verification code is 849201." , "external_message_id" : "gw-msg-00993" , "delivery_status" : "submitted" , "direction" : "outbound" , "callback_url" : "https://your-instance.laracopilot.com/api/sms-gateways/1/dlr" , "remote_response" : { "message_id" : "gw-msg-00993" , "status" : 0 }, "error_message" : null , "requested_at" : "2024-03-20T12:00:00.000000Z" , "submitted_at" : "2024-03-20T12:00:01.000000Z" , "delivered_at" : null } }
{ "message" : "SMS request processed." , "data" : { "id" : 59 , "sms_gateway_id" : 1 , "tenant_id" : null , "to_number" : "+447911999000" , "from_sender" : "LaraCopilot" , "message" : "Test message." , "external_message_id" : "3f2a1c4b-..." , "delivery_status" : "failed" , "direction" : "outbound" , "callback_url" : "https://your-instance.laracopilot.com/api/sms-gateways/1/dlr" , "remote_response" : { "exception" : "Connection refused" }, "error_message" : "Connection refused" , "requested_at" : "2024-03-20T12:05:00.000000Z" , "submitted_at" : null , "delivered_at" : null } }
