SDK

PHP SDK

A lightweight, framework-agnostic PHP SDK: SMS, contacts, lists, sender IDs and SMTP email.

Runtime

PHP 7.4+

Package

messageglobe/sdk

Packagist ↗

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

Email

SMTP

send (HTML + text, attachments)

Installation

Add the SDK to your project

Shell
composer require messageglobe/sdk
View the package on Packagist

Quick 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.

PHP
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'));
Get your API token

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.

PHP
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.

Sending a message
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.06

The 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.

Automatic type
(new SmsMessage())    ->to('393612345678')    ->from('YourName')    ->messageAutoType('Привет 😀');   // becomes unicode automatically
Multiple recipients
$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;}
Checking the status
$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.

DLR webhook payload
{    "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.

Explore the Messaging API

Contact management

Contact records inside your lists

Contacts live inside a list identified by its group id. Use the same API token as SMS.

PHP
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.

PHP
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.

PHP
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.

Read the AGCOM code of conduct

Email

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.

PHP
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.

MessageGlobe SMTP 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);
Explore the Email API

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.

PHP
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}
TypeRaised when
ConfigurationExceptionConfiguration is missing or invalid.
ValidationExceptionA message or a contact fails client-side validation.
ApiExceptionA REST endpoint (SMS, Contacts, Lists, Sender IDs) returns an error.
TransportExceptionNetwork failure, timeout or an undecodable response.
EmailExceptionSMTP 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.

PHP
// 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.

Ready to integrate?

Open an account, generate your API token and send your first message in minutes.

MessageGlobe Support

Fill in the form and we'll reply as soon as possible.

Checking agent availability…