PHPackages                             messageglobe/sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. messageglobe/sdk

ActiveLibrary[HTTP & Networking](/categories/http)

messageglobe/sdk
================

Official MessageGlobe PHP SDK — send SMS via the REST API and email via SMTP. Framework- and CMS-agnostic.

v1.0.0(1mo ago)04MITPHPPHP >=7.4CI passing

Since Jul 16Pushed 1mo agoCompare

[ Source](https://github.com/Message-Globe/messageglobe-php)[ Packagist](https://packagist.org/packages/messageglobe/sdk)[ Docs](https://messageglobe.com)[ RSS](/packages/messageglobe-sdk/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (2)Versions (2)Used By (0)

MessageGlobe PHP SDK
====================

[](#messageglobe-php-sdk)

**A lightweight, framework-agnostic PHP SDK for [MessageGlobe](https://messageglobe.com)** — send SMS, manage contacts, lists and sender IDs, and send email over SMTP.

**English** · [Italiano](README.it.md)

[![CI](https://github.com/Message-Globe/messageglobe-php/actions/workflows/ci.yml/badge.svg)](https://github.com/Message-Globe/messageglobe-php/actions/workflows/ci.yml)

---

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](https://dashboard.messageglobe.com/developers)) authorises every REST feature — SMS, Contacts, Lists, and Sender IDs. Email is configured separately over SMTP.

Table of contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick start](#quick-start)
- [SMS](#sms)
- [Contacts](#contacts)
- [Lists (groups)](#lists-groups)
- [Sender IDs](#sender-ids)
- [Email](#email)
- [Error handling](#error-handling)
- [Custom HTTP client](#custom-http-client)
- [Testing](#testing)
- [License](#license)

Features
--------

[](#features)

FeatureTransportOperations**SMS**REST API v3send, delivery status**Contacts**REST API v3create, delete**Lists (groups)**REST API v3create, show, update, delete, list**Sender IDs**REST API v3list, show, create, delete**Email**SMTPsend (HTML + text, attachments)Requirements
------------

[](#requirements)

- PHP **7.4+**
- `ext-curl` and `ext-json` (for the REST features)
- [`phpmailer/phpmailer`](https://github.com/PHPMailer/PHPMailer) (pulled in automatically, for email)

Installation
------------

[](#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
-----------

[](#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('Hi Jane')
        ->text('Hi Jane')
);
```

SMS
---

[](#sms)

### Configuration

[](#configuration)

Get your API token from the [developers dashboard](https://dashboard.messageglobe.com/developers). 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

[](#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

[](#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

[](#checking-status)

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

### Delivery report (DLR) callbacks

[](#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)

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

[](#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

[](#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)
--------------

[](#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
----------

[](#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
-----

[](#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('Report readySee attachment.')
        ->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

[](#using-messageglobes-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
--------------

[](#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, ...)
}
```

ExceptionThrown 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 failsCustom HTTP client
------------------

[](#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
-------

[](#testing)

```
composer install
composer test
```

License
-------

[](#license)

Released under the [MIT License](LICENSE).

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance90

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity33

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

46d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d9d297e7b636994222fc4f2b9846ed796fe5f09ea3c505308c29713abcda33b8?d=identicon)[tiltroom](/maintainers/tiltroom)

---

Top Contributors

[![tiltroom](https://avatars.githubusercontent.com/u/45572888?v=4)](https://github.com/tiltroom "tiltroom (8 commits)")

---

Tags

sdkrestemailsmsmessagingsmtpmessageglobe

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/messageglobe-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/messageglobe-sdk/health.svg)](https://phpackages.com/packages/messageglobe-sdk)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.8k40.0k](/packages/matomo-matomo)[infobip/infobip-api-php-client

PHP library for consuming Infobip's API

962.0M10](/packages/infobip-infobip-api-php-client)[sendpulse/rest-api

Official PHP SDK for the SendPulse REST API

1201.3M7](/packages/sendpulse-rest-api)[openapi/openapi-sdk

Minimal and agnostic PHP SDK for Openapi® (https://openapi.com)

164.6k1](/packages/openapi-openapi-sdk)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)