SDK

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

Email

SMTP

send (HTML + text, attachments)

Installation

Add the SDK to your project

Shell
npm install @messageglobe/sdk

The package is not published on npm yet: install it straight from GitHub.

Shell
npm install github:Message-Globe/messageglobe-nodejs

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.

TypeScript
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',});
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.

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

Sending a message
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.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
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'
Multiple recipients
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);}
Checking the status
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.

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.

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

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

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

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.

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

MessageGlobe SMTP 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',  }),);
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.

TypeScript
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;  }}
TypeRaised when
ConfigurationErrorConfiguration is missing or invalid.
ValidationErrorA message or a contact fails client-side validation.
ApiErrorA REST endpoint (SMS, Contacts, Lists, Sender IDs) returns an error.
TransportErrorNetwork failure, timeout or an undecodable response.
EmailErrorSMTP 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.

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

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…