README

MessageGlobe PHP SDK

A lightweight, framework-agnostic PHP SDK for MessageGlobe — send SMS, manage contacts, lists and sender IDs, and send email over SMTP.

English · Italiano

The SDK has no framework or CMS dependencies and drops cleanly into Laravel, Symfony, WordPress, or plain PHP. A single API token (copied from the developers dashboard) authorises every REST feature — SMS, Contacts, Lists, and Sender IDs. Email is configured separately over SMTP.

Features
Requirements
Installation
Quick start
SMS
Contacts
Lists (groups)
Sender IDs
Email
Error handling
Custom HTTP client
Testing
License

Features

Feature	Transport	Operations
SMS	REST API v3	send, delivery status
Contacts	REST API v3	create, delete
Lists (groups)	REST API v3	create, show, update, delete, list
Sender IDs	REST API v3	list, show, create, delete
Email	SMTP	send (HTML + text, attachments)

Requirements

PHP 7.4+
ext-curl and ext-json (for the REST features)
phpmailer/phpmailer (pulled in automatically, for email)

Installation

composer require messageglobe/sdk

Not yet published on Packagist? Until then, install directly from GitHub by adding the repository to your composer.json, then requiring a tagged release (or dev-main):
{
  "repositories": [
    { "type": "vcs", "url": "https://github.com/Message-Globe/messageglobe-php" }
  ]
}
composer require messageglobe/sdk:^1.0

Quick start

Use the unified facade, or each client on its own.

use MessageGlobe\MessageGlobe;
use MessageGlobe\Sms\SmsMessage;
use MessageGlobe\Contacts\ContactRequest;
use MessageGlobe\Email\EmailMessage;

$mg = MessageGlobe::create([
    // Copy your token from https://dashboard.messageglobe.com/developers.
    // This one token powers all REST features (SMS, Contacts, Lists, Sender IDs).
    '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

Configuration

Get your API token from the developers dashboard. The same ApiConfig is shared by every REST client.

use MessageGlobe\ApiConfig;
use MessageGlobe\Sms\SmsClient;

$client = new SmsClient(new ApiConfig('XX|your-api-token'));

// Optionally set the response language ("en" or "it"):
$client = new SmsClient(new ApiConfig('XX|your-api-token', ApiConfig::DEFAULT_BASE_URL, ApiConfig::LANGUAGE_IT));

Sending a message

SmsMessage is a fluent builder. There are two gateways:

HQ (->highQuality()) — custom sender_id and delivery reports. sender_id is required.
LQ (->lowQuality()) — no custom sender, no delivery report.

use MessageGlobe\Sms\SmsMessage;

$response = $client->send(
    (new SmsMessage())
        ->to('393612345678')        // call multiple times, or pass "n1,n2" for several recipients
        ->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 vs 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('Привет 😀');   // -> unicode automatically

Multiple recipients

$response = $client->send(
    (new SmsMessage())
        ->to('393612345678,880172145789')  // or chain ->to() calls
        ->from('YourName')
        ->message('Hello everyone')
        ->highQuality()
);

foreach ($response->all() as $result) {
    echo $result->recipient(), ' => ', $result->messageId(), PHP_EOL;
}

Checking status

$result = $client->status('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx');
echo $result->status();      // e.g. "Delivered"
echo $result->updatedAt();

Delivery report (DLR) callbacks

When you pass dlrCallbackUrl() with the HQ gateway, MessageGlobe POSTs a JSON payload to your URL for each 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.

Contacts

Contacts live inside a list identified by its group id (the list uid). Use the same ApiConfig / API token as SMS.

use MessageGlobe\ApiConfig;
use MessageGlobe\Contacts\ContactsClient;
use MessageGlobe\Contacts\ContactRequest;

$client = new ContactsClient(new ApiConfig('XX|your-api-token'));

Creating a contact

At least one of phone or email is required; firstName and lastName are optional.

$contact = $client->create('list_uid_example', (new ContactRequest())
    ->phone('393310000000')
    ->firstName('Jane')
    ->lastName('Doe'));

echo $contact->uid();       // "contact_uid_example"
echo $contact->status();    // "subscribe"
echo $contact->createdAt();

Deleting a contact

Provide the list group id and the contact uid returned at creation.

$client->delete('list_uid_example', 'contact_uid_example');

A failed delete (e.g. the contact does not exist) throws an ApiException with apiErrorCode() 1002 ("Risorsa non trovata").

Lists (groups)

A list — or group — is the container that 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 groups (raw, paginated API data)
$page = $client->all();

Group exposes uid(), name(), createdAt(), updatedAt(), and raw() for the full payload. all() returns the raw decoded data (including pagination metadata) because the API does not document a fixed shape.

Sender IDs

Manage the sender IDs (custom senders used with the HQ gateway) on your account.

use MessageGlobe\ApiConfig;
use MessageGlobe\Senders\SendersClient;
use MessageGlobe\Senders\SenderIdRequest;

$client = new SendersClient(new ApiConfig('XX|your-api-token'));

// List all sender IDs
foreach ($client->all() as $sender) {
    echo $sender->senderId(), ' => ', $sender->status(), PHP_EOL; // "active" / "pending"
}

// Look one up by name
$sender = $client->show('YourName');

// Create a new one (submitted for approval — 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');

A lookup or delete of an unknown sender ID throws an ApiException (HTTP 404, message locale.exceptions.not_found).

Email

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'))
);

Encryption options: SmtpConfig::ENCRYPTION_TLS (STARTTLS), ENCRYPTION_SSL (SMTPS), or ENCRYPTION_NONE. Omit username/password for an unauthenticated relay.

Using MessageGlobe's SMTP server

MessageGlobe provides SMTP on dashboard.messageglobe.com:465 (SSL). Your username is your MessageGlobe login and your password is your API token. There's a preset for this:

$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

Every exception thrown by the SDK implements MessageGlobe\Exception\MessageGlobeExceptionInterface, so you can catch them all in one place:

use MessageGlobe\Exception\ApiException;
use MessageGlobe\Exception\ValidationException;
use MessageGlobe\Exception\MessageGlobeExceptionInterface;

try {
    $client->send($sms);
} catch (ValidationException $e) {
    // Client-side validation failed (bad number, missing sender_id, ...)
} 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());       // ['recipient' => '... non è un numero mobile valido']
} catch (MessageGlobeExceptionInterface $e) {
    // Any other SDK error (transport, email, configuration, ...)
}

Exception	Thrown when
`ConfigurationException`	Invalid or missing configuration
`ValidationException`	A message or contact fails client-side validation
`ApiException`	A REST endpoint (SMS, Contacts, Lists, Senders) errors
`TransportException`	Network failure or an undecodable response
`EmailException`	SMTP delivery fails

Custom HTTP client

Every REST client (SmsClient, ContactsClient, GroupsClient, SendersClient) uses a zero-dependency cURL client by default. You can supply your own by implementing MessageGlobe\Http\HttpClientInterface — handy for testing or for reusing your application's HTTP stack.

$client = new SmsClient($config, new MyHttpClient());
$groups = new GroupsClient($config, new MyHttpClient());

Testing

composer install
composer test

License

Released under the MIT License.

messageglobe / sdk

Maintainers

Package info

Statistics

Security