PHP SDK
A lightweight, framework-agnostic PHP SDK: SMS, contacts, lists, sender IDs and SMTP email.
Runtime
PHP 7.4+
Dependencies
The ext-curl and ext-json extensions; PHPMailer for email (installed automatically).
Licence
MIT
Open source on GitHub
The SDK has no framework dependencies and drops cleanly into Laravel, Symfony, WordPress or plain PHP. A single API token — the one from the developers dashboard — authorises every REST feature: SMS, contacts, lists and sender IDs. Email is configured separately over SMTP.
Features
Five modules, one integration
SMS
REST API v3
send, delivery status
Contact management
REST API v3
create, delete
Lists (groups)
REST API v3
create, show, update, delete, list
Sender ID
REST API v3
list, show, create, delete
SMTP
send (HTML + text, attachments)
Installation
Add the SDK to your project
composer require messageglobe/sdkQuick start
From token to first send
Use the unified facade, or each client on its own. Copy the token from the developers dashboard — it covers every REST feature.
use MessageGlobe\MessageGlobe;use MessageGlobe\Sms\SmsMessage;use MessageGlobe\Contacts\ContactRequest;use MessageGlobe\Email\EmailMessage; $mg = MessageGlobe::create([ // Copy your token from the developers dashboard. // This one token powers all REST features. 'api_token' => 'XX|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', 'smtp' => [ 'host' => 'smtp.messageglobe.com', 'port' => 587, 'from_address' => 'no-reply@yourapp.com', 'from_name' => 'YourApp', 'username' => 'smtp-user', 'password' => 'smtp-password', 'encryption' => 'tls', ],]); // Send an SMS$response = $mg->sms()->send( (new SmsMessage()) ->to('393612345678') ->from('YourName') ->message('This is a test message') ->highQuality());echo $response->messageId(); // Create a contact$contact = $mg->contacts()->create('list_uid_example', (new ContactRequest())->phone('393310000000'));echo $contact->uid(); // Send an email$mg->email()->send( (new EmailMessage()) ->to('jane@example.com', 'Jane Doe') ->subject('Welcome') ->html('<h1>Hi Jane</h1>') ->text('Hi Jane'));SMS
Sending, gateways and delivery reports
The same configuration is shared by every REST client. You can set the language of the API responses to Italian or English.
use MessageGlobe\ApiConfig;use MessageGlobe\Sms\SmsClient; $client = new SmsClient(new ApiConfig('XX|your-api-token')); // Language of the API responses: "en" or "it".$client = new SmsClient(new ApiConfig('XX|your-api-token', ApiConfig::DEFAULT_BASE_URL, ApiConfig::LANGUAGE_IT));Gateway HQ ->highQuality()
Custom sender ID and delivery reports. The sender field is required.
Gateway LQ ->lowQuality()
No custom sender and no delivery report.
use MessageGlobe\Sms\SmsMessage; $response = $client->send( (new SmsMessage()) ->to('393612345678') // one number, or several ->to() calls ->from('YourName') // sender ID, max 11 chars if alphanumeric ->message('Hello world') ->highQuality() ->dlrCallbackUrl('https://yourapp.com/webhooks/dlr') // optional, HQ only); $result = $response->first();echo $result->messageId(); // "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"echo $result->status(); // "Sent"echo $result->cost(); // 0.06The message type (plain or unicode) defaults to plain. Let the SDK pick it from the content: messages with non-GSM characters (emoji, Cyrillic, …) are sent as unicode.
(new SmsMessage()) ->to('393612345678') ->from('YourName') ->messageAutoType('Привет 😀'); // becomes unicode automatically$response = $client->send( (new SmsMessage()) ->to('393612345678,880172145789') // or chain several ->to() calls ->from('YourName') ->message('Hello everyone') ->highQuality()); foreach ($response->all() as $result) { echo $result->recipient(), ' => ', $result->messageId(), PHP_EOL;}$result = $client->status('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'); echo $result->status(); // e.g. "Delivered"echo $result->updatedAt();With the HQ gateway and a DLR callback, MessageGlobe POSTs a JSON payload to your endpoint on every delivery update.
{ "message_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "recipient": "393612345678", "sender_id": "YourName", "status_code": 1, "status": "Delivered", "updated_at": "2024-06-28T11:41:51.000000Z"}status_code values: 1 Delivered, 2 Failed, 8 Sent.
Contact management
Contact records inside your lists
Contacts live inside a list identified by its group id. Use the same API token as SMS.
use MessageGlobe\ApiConfig;use MessageGlobe\Contacts\ContactsClient;use MessageGlobe\Contacts\ContactRequest; $client = new ContactsClient(new ApiConfig('XX|your-api-token')); // At least one of phone or email is required.$contact = $client->create('list_uid_example', (new ContactRequest()) ->phone('393310000000') ->firstName('Jane') ->lastName('Doe')); echo $contact->uid(); // "contact_uid_example"echo $contact->status(); // "subscribe" // Delete by passing the list and the contact uid.$client->delete('list_uid_example', 'contact_uid_example');Lists (groups)
The container for your contacts
A list — or group — is the container contacts belong to: its uid is the group id used by the Contacts client.
use MessageGlobe\ApiConfig;use MessageGlobe\Contacts\GroupsClient; $client = new GroupsClient(new ApiConfig('XX|your-api-token')); $group = $client->create('Newsletter subscribers');$uid = $group->uid(); $group = $client->show($uid);$group = $client->update($uid, 'VIP subscribers'); $client->delete($uid); // List all the lists (raw, paginated data)$page = $client->all();Sender ID
Manage the senders on your account
Sender IDs are the custom senders used with the HQ gateway. You can list them, look them up, request new ones and delete them via the API.
use MessageGlobe\ApiConfig;use MessageGlobe\Senders\SendersClient;use MessageGlobe\Senders\SenderIdRequest; $client = new SendersClient(new ApiConfig('XX|your-api-token')); // List all sender IDsforeach ($client->all() as $sender) { echo $sender->senderId(), ' => ', $sender->status(), PHP_EOL; // "active" / "pending"} // Look up a sender ID by name$sender = $client->show('YourName'); // Create a new one: all fields are required, 3-11 chars.$sender = $client->create((new SenderIdRequest()) ->senderId('YourName') ->company('Your Company') ->taxCode('ABCDEF12G34H567I') ->vatCode('01234567890') ->address('Via Roma 1') ->city('Rome') ->province('RM') ->country('IT') ->emailAddress('you@example.com') ->phone('391234567890') ->pecAddress('you@pec.example.com')); // Delete by name$client->delete('YourName');In Italy alphanumeric aliases follow the AGCOM code of conduct: new sender IDs are submitted for approval.
Transactional email over SMTP
Send HTML and text email with attachments, CC, BCC and reply-to. Encryption options are TLS (STARTTLS), SSL (SMTPS) or none.
use MessageGlobe\Email\Attachment;use MessageGlobe\Email\EmailClient;use MessageGlobe\Email\EmailMessage;use MessageGlobe\Email\SmtpConfig; $client = new EmailClient(new SmtpConfig( 'smtp.messageglobe.com', 587, 'no-reply@yourapp.com', 'YourApp', 'smtp-user', 'smtp-password', SmtpConfig::ENCRYPTION_TLS)); $client->send( (new EmailMessage()) ->to('jane@example.com', 'Jane Doe') ->cc('team@example.com') ->replyTo('support@yourapp.com') ->subject('Your report') ->html('<h1>Report ready</h1><p>See attachment.</p>') ->text('Report ready. See attachment.') ->attach(Attachment::fromPath('/path/to/report.pdf')) ->attach(Attachment::fromContent($csvString, 'data.csv', 'text/csv')));MessageGlobe provides SMTP on dashboard.messageglobe.com:465 (SSL): your username is your login and your password is the API token. There is a dedicated preset.
$config = SmtpConfig::forMessageGlobe( 'you@yourlogin.com', // MessageGlobe login username 'XX|your-api-token', // API token, used as the SMTP password 'no-reply@yourapp.com', 'YourApp'); $client = new EmailClient($config);Error handling
One base type to catch
Every error raised by the SDK derives from a common type: handle them all in one place, or tell them apart case by case.
use MessageGlobe\Exception\ApiException;use MessageGlobe\Exception\ValidationException;use MessageGlobe\Exception\MessageGlobeExceptionInterface; try { $client->send($sms);} catch (ValidationException $e) { // Client-side validation failed} catch (ApiException $e) { // The API returned an error echo $e->getMessage(); // "Invalid params" echo $e->apiErrorCode(); // 200 echo $e->httpStatusCode(); // 422 print_r($e->errors());} catch (MessageGlobeExceptionInterface $e) { // Any other SDK error}| Type | Raised when |
|---|---|
| ConfigurationException | Configuration is missing or invalid. |
| ValidationException | A message or a contact fails client-side validation. |
| ApiException | A REST endpoint (SMS, Contacts, Lists, Sender IDs) returns an error. |
| TransportException | Network failure, timeout or an undecodable response. |
| EmailException | SMTP delivery fails. |
Base type shared by every error: MessageGlobeExceptionInterface
HTTP client
Use your own network stack
Every REST client uses a dependency-free default transport. You can swap in your own — handy for tests, for adding retries, or for reusing your application's HTTP stack.
// Implement MessageGlobe\Http\HttpClientInterface to use your own HTTP stack.$client = new SmsClient($config, new MyHttpClient());$groups = new GroupsClient($config, new MyHttpClient());Other SDKs
Same API, other languages
The official SDKs are feature-aligned: the language changes, the workflow does not.
Works with your favorite tools
Connect MessageGlobe to the platforms you already use — e-commerce, CMS and thousands of apps, without writing a single line of code.
Ready to integrate?
Open an account, generate your API token and send your first message in minutes.