Simply Connect for Laravel

The official, expressive Laravel SDK for the Simply Connect External API. Send SMS messages through your Android phones and modem gateways using familiar Laravel conventions.

English · API documentation

Why it feels at home in Laravel

• fluent SMS sending with sensible defaults;
• automatic package discovery and environment-based configuration;
• native Laravel notification channel and queue support;
• named connections and friendly endpoint aliases;
• typed, immutable responses and delivery-status enums;
• safe idempotency keys with explicit unknown-outcome handling;
• focused exceptions for authentication, validation, rate limits and server failures;
• a first-class fake with expressive test assertions;
• no automatic retry that could accidentally duplicate an SMS.

Requirements

Your Simply Connect API key needs SMS_SEND. Add MESSAGES_READ if the application retrieves delivery status.

Installation

Install the package through Composer:

Laravel discovers the service provider and facade automatically. Add the API key and default SMS endpoint to .env:

Create API keys in Developer → API keys in the Simply Connect panel. The secret is shown once; store it in your secret manager and never commit it.

Publish the configuration only when you need multiple connections or named endpoints:

Sending SMS

The default endpoint comes from SIMPLY_CONNECT_SMS_ENDPOINT_ID:

Named endpoints

Give gateway UUIDs stable names in config/simply-connect.php:

Then select a sender without leaking UUIDs into business code:

via() also accepts a raw endpoint UUID. List endpoints available to the current API key with:

Domain objects as recipients

Implement HasSmsNumber to pass a domain object directly:

Laravel Notifications

Return an SmsMessage from toSimplyConnect():

Expose the route on your notifiable model:

Send it like every other Laravel notification:

Laravel queues the notification when it implements ShouldQueue. Configure and run your queue worker as usual.

Dependency injection

The facade is optional. Inject the public contract into application services:

Delivery status

The API key needs MESSAGES_READ:

UNKNOWN is intentional: the platform cannot prove whether the carrier performed the side effect. Do not turn it into an automatic retry.

Idempotency and network failures

The SDK generates an Idempotency-Key for every send. Provide a business key when the same operation can be retried by a queue or command:

If the connection disappears after submission, the SDK throws UnknownOutcomeException. Retry only with the key from the exception and the exact same endpoint, recipient and body:

Reusing a key with different content throws IdempotencyConflictException and never queues another SMS.

Error handling

All package exceptions extend SimplyConnectException and expose statusCode, problemCode, correlationId and a sanitized context array.

Testing

No HTTP request is performed after enabling the fake:

You can also use SimplyConnect::assertNothingSent().

Multiple Simply Connect accounts

Define additional connections in the published configuration, then select one explicitly:

Security

• Keep API keys in environment variables or a secret manager.
• Grant only the required scopes and endpoint access.
• Never log request headers, SMS bodies or complete phone numbers.
• Rotate a key immediately after suspected exposure.
• Report vulnerabilities through GitHub private vulnerability reporting; see SECURITY.md.

Contributing

See CONTRIBUTING.md. Run the full quality gate with:

License

Simply Connect for Laravel is open-source software licensed under the MIT license.