MsGineClient

Complete API reference for the MsGineClient class.

Constructor

new MsGineClient(config)

Creates a new MsGine SDK client instance.

import { MsGineClient } from '@msgine/sdk'

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  baseUrl: 'https://api.msgine.net/api/v1', // optional
  timeoutMs: 30000, // optional
  retryConfig: { // optional
    maxRetries: 3,
    initialDelayMs: 1000,
    maxDelayMs: 10000,
    backoffMultiplier: 2
  }
})

Parameters

Parameter	Type	Required	Description
config.apiToken	string	Yes	Your MsGine API token
config.baseUrl	string	No	API base URL (default: https://api.msgine.net/api/v1)
config.timeoutMs	number	No	Request timeout in milliseconds (default: 30000)
config.retryConfig	RetryConfig	No	Custom retry configuration
config.onError	function	No	Error callback handler

Methods

sendSms(params)

Send an SMS message to one or more recipients.

const result = await client.sendSms({
  to: '+256701521269',
  message: 'Hello from MsGine!',
  from: 'MyApp', // optional
  callbackUrl: 'https://myapp.com/webhook' // optional
})

Parameters

Parameter	Type	Required	Description
to	string | string[]	Yes	Recipient phone number(s) in E.164 format
message	string	Yes	Message content (max 1600 characters)
from	string	No	Sender ID (default: your account sender ID)
callbackUrl	string	No	Webhook URL for delivery status updates

Returns

Returns a Promise<SendSmsResponse>:

{
  id: string              // Unique message identifier
  sid: string | null      // Provider-specific ID
  channel: string         // Message channel ("sms")
  to: string[]           // Recipient phone numbers
  from: string           // Sender ID
  content: string        // Message content
  status: MessageStatus  // Current status
  cost: number          // Message cost
  currency: string      // Currency code
  createdAt: string     // ISO 8601 timestamp
  updatedAt?: string    // ISO 8601 timestamp
}

Example

try {
  const result = await client.sendSms({
    to: ['+256701521269', '+256701234567'],
    message: 'Welcome to MsGine!',
    from: 'MyApp'
  })

  console.log('Message sent:', result.id)
  console.log('Status:', result.status)
  console.log('Cost:', result.cost, result.currency)
} catch (error) {
  console.error('Failed to send SMS:', error)
}

getMessageStatus(messageId)

Retrieve the delivery status of a sent message.

const status = await client.getMessageStatus('msg_1234567890')

Parameters

Parameter	Type	Required	Description
messageId	string	Yes	The message ID returned from sendSms

Returns

Returns a Promise<MessageStatus>:

{
  id: string
  status: 'pending' | 'sent' | 'delivered' | 'failed'
  to: string[]
  updatedAt: string
  failureReason?: string
}

getAccount()

Retrieve your account information and current balance.

const account = await client.getAccount()

Returns

Returns a Promise<AccountInfo>:

{
  id: string
  email: string
  balance: number
  currency: string
  plan: string
  createdAt: string
}

listMessages(options)

List sent messages with pagination.

const messages = await client.listMessages({
  page: 1,
  limit: 20,
  status: 'delivered'
})

Parameters

Parameter	Type	Required	Description
page	number	No	Page number (default: 1)
limit	number	No	Items per page (default: 20, max: 100)
status	MessageStatus	No	Filter by status

Returns

Returns a Promise<MessageListResponse>:

{
  data: SendSmsResponse[]
  pagination: {
    page: number
    limit: number
    total: number
    pages: number
  }
}

Configuration

Retry Configuration

Customize how the SDK retries failed requests:

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  retryConfig: {
    maxRetries: 3,           // Maximum number of retries
    initialDelayMs: 1000,    // Initial delay between retries
    maxDelayMs: 10000,       // Maximum delay between retries
    backoffMultiplier: 2     // Exponential backoff multiplier
  }
})

Custom Error Handler

Add a custom error handler for logging and monitoring:

const client = new MsGineClient({
  apiToken: process.env.MSGINE_API_TOKEN!,
  onError: (error) => {
    // Send to monitoring service
    monitoringService.trackError({
      name: error.name,
      message: error.message,
      code: error.code,
      statusCode: error.statusCode
    })
  }
})

Type Definitions

See the complete Type Reference for all available types and interfaces.

Error Handling

See the Error Handling Guide for detailed information about handling errors.

Next Steps

• Sending SMS - Detailed SMS sending guide
• Error Handling - Handle errors gracefully
• Type Reference - Complete type definitions