Node.js SDK
A TypeScript Node.js SDK with ESM and CommonJS builds: SMS, contacts, lists, sender IDs and SMTP email.
Runtime
Node.js 18+
Package
@messageglobe/sdk
npm · coming soon
Dependencies
None: the REST client uses the built-in fetch; nodemailer for email (installed automatically).
Licence
MIT
Open source on GitHub
The SDK has no framework dependencies and drops cleanly into Express, Nest, Next.js or a plain script. 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
npm install @messageglobe/sdkThe package is not published on npm yet: install it straight from GitHub.
npm install github:Message-Globe/messageglobe-nodejsQuick 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.
import { MessageGlobe } from '@messageglobe/sdk'; const mg = new MessageGlobe({ // Copy your token from the developers dashboard. // This one token powers all REST features. apiToken: 'XX|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx', smtp: { host: 'smtp.messageglobe.com', port: 587, fromAddress: 'no-reply@yourapp.com', fromName: 'YourApp', username: 'smtp-user', password: 'smtp-password', encryption: 'tls', },}); // Send an SMSconst response = await mg.sms.send({ to: '393612345678', from: 'YourName', message: 'This is a test message', gateway: 'HQ',});console.log(response.messageId); // Create a contactconst contact = await mg.contacts.create('list_uid_example', { phone: '393310000000' });console.log(contact.uid); // Send an emailawait mg.email.send({ to: { email: 'jane@example.com', name: '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.
import { SmsClient } from '@messageglobe/sdk'; const client = new SmsClient({ apiToken: 'XX|your-api-token' }); // Language of the API responses: "en" or "it".const italian = new SmsClient({ apiToken: 'XX|your-api-token', acceptLanguage: 'it' }); // CommonJS works too:// const { MessageGlobe } = require('@messageglobe/sdk');Gateway HQ gateway: 'HQ'
Custom sender ID and delivery reports. The sender field is required.
Gateway LQ gateway: 'LQ'
No custom sender and no delivery report.
const response = await client.send({ to: '393612345678', // a single number, "n1,n2" or an array from: 'YourName', // sender ID, max 11 chars if alphanumeric message: 'Hello world', gateway: 'HQ', dlrCallbackUrl: 'https://yourapp.com/webhooks/dlr', // optional, HQ only}); const [result] = response.results;console.log(result.messageId); // "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"console.log(result.status); // "Sent"console.log(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.
await client.send({ to: '393612345678', from: 'YourName', message: 'Привет 😀', type: 'auto', // becomes unicode automatically}); // The detection is exported on its own too:import { detectSmsType } from '@messageglobe/sdk'; detectSmsType('Hello world'); // 'plain'detectSmsType('Привет 😀'); // 'unicode'const response = await client.send({ to: ['393612345678', '880172145789'], // or "393612345678,880172145789" from: 'YourName', message: 'Hello everyone',}); for (const result of response.results) { console.log(result.recipient, '=>', result.messageId);}const result = await client.status('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'); console.log(result.status); // e.g. "Delivered"console.log(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.
import { ContactsClient } from '@messageglobe/sdk'; const client = new ContactsClient({ apiToken: 'XX|your-api-token' }); // At least one of phone or email is required.const contact = await client.create('list_uid_example', { phone: '393310000000', firstName: 'Jane', lastName: 'Doe',}); console.log(contact.uid); // "contact_uid_example"console.log(contact.status); // "subscribe" // Delete by passing the list and the contact uid.await 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.
import { GroupsClient } from '@messageglobe/sdk'; const client = new GroupsClient({ apiToken: 'XX|your-api-token' }); const group = await client.create('Newsletter subscribers');const uid = group.uid; await client.show(uid);await client.update(uid, 'VIP subscribers');await client.delete(uid); // List all the lists (raw, paginated data)const page = await client.list();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.
import { SendersClient } from '@messageglobe/sdk'; const client = new SendersClient({ apiToken: 'XX|your-api-token' }); // List all sender IDsfor (const sender of await client.list()) { console.log(sender.senderId, '=>', sender.status); // "active" / "pending"} // Look up a sender ID by nameconst sender = await client.show('YourName'); // Create a new one: all fields are required, 3-11 chars.await client.create({ 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 nameawait 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.
import { EmailClient } from '@messageglobe/sdk'; const client = new EmailClient({ host: 'smtp.messageglobe.com', port: 587, fromAddress: 'no-reply@yourapp.com', fromName: 'YourApp', username: 'smtp-user', password: 'smtp-password', encryption: 'tls',}); await client.send({ to: { email: 'jane@example.com', name: '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.', attachments: [ { filename: 'report.pdf', path: '/path/to/report.pdf' }, { filename: 'data.csv', content: csvString, contentType: 'text/csv' }, ],}); // Release the connection pool when shutting down.await client.close();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.
import { EmailClient, messageGlobeSmtp } from '@messageglobe/sdk'; const client = new EmailClient( messageGlobeSmtp({ username: 'you@yourlogin.com', // MessageGlobe login username apiToken: 'XX|your-api-token', // API token, used as the SMTP password fromAddress: 'no-reply@yourapp.com', fromName: 'YourApp', }),);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.
import { ApiError, MessageGlobeError, ValidationError } from '@messageglobe/sdk'; try { await client.send(sms);} catch (error) { if (error instanceof ValidationError) { // Client-side validation failed } else if (error instanceof ApiError) { // The API returned an error console.log(error.message); // "Invalid params" console.log(error.apiErrorCode); // 200 console.log(error.httpStatusCode); // 422 console.log(error.errors); } else if (error instanceof MessageGlobeError) { // Any other SDK error } else { throw error; }}| Type | Raised when |
|---|---|
| ConfigurationError | Configuration is missing or invalid. |
| ValidationError | A message or a contact fails client-side validation. |
| ApiError | A REST endpoint (SMS, Contacts, Lists, Sender IDs) returns an error. |
| TransportError | Network failure, timeout or an undecodable response. |
| EmailError | SMTP delivery fails. |
Base type shared by every error: MessageGlobeError
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.
import { SmsClient, type HttpClient } from '@messageglobe/sdk'; const httpClient: HttpClient = { async request({ method, url, headers, body, signal }) { const response = await fetch(url, { method, headers, body, signal }); return { statusCode: response.status, body: await response.text(), headers: Object.fromEntries(response.headers), }; },}; const client = new SmsClient({ apiToken: 'XX|your-api-token', httpClient });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.