Quick Start

Send your first SMS message in minutes with the MsGine SDK.

1. Get Your API Key

First, you'll need an API key:

1. Sign up for a MsGine account
2. Navigate to the Developer Dashboard
3. Generate a new API key
4. Copy the key (it won't be shown again)

2. Set Up Environment Variables

Store your API key securely using environment variables:

# .env
MSGINE_API_KEY=your-api-key-here

TIP

Never commit your API key to version control. Add .env to your .gitignore file.

3. Initialize the Client

Create a new MsGine client instance:

import { MsGineClient } from '@msgine/sdk'

const client = new MsGineClient({
  apiKey: process.env.MSGINE_API_KEY!,
})

4. Send Your First SMS

Now you're ready to send a message:

const result = await client.sms.send({
  to: '+256701521269',
  message: 'Hello from MsGine!'
})

console.log('Message sent:', result.id)
console.log('Status:', result.status)
console.log('Cost:', result.cost, result.currency)

Complete Example

Here's a complete working example:

import { MsGineClient, MsGineError } from '@msgine/sdk'

const client = new MsGineClient({
  apiKey: process.env.MSGINE_API_KEY!,
})

async function sendMessage() {
  try {
    const result = await client.sms.send({
      to: '+256701521269',
      message: 'Your verification code is 123456'
    })

    console.log('✅ Message sent successfully!')
    console.log('Message ID:', result.id)
    console.log('Status:', result.status)
    console.log('Recipients:', result.to)
    console.log('Cost:', result.cost, result.currency) // e.g., 30 UGX
    console.log('Sent at:', result.createdAt)
  } catch (error) {
    if (error instanceof MsGineError) {
      console.error('❌ API Error:', error.message)
      console.error('Status Code:', error.statusCode)
      console.error('Error Code:', error.code)
    } else {
      console.error('❌ Unexpected error:', error)
    }
  }
}

sendMessage()

Understanding the Response

The sms.send() method returns a SendSmsResponse object:

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

Message Statuses

Messages can have the following statuses:

• pending - Message is queued for delivery
• sent - Message has been sent to the carrier
• delivered - Message was successfully delivered
• failed - Message delivery failed

What's Next?

Now that you've sent your first message, explore more features:

• Send Batch Messages - Send to multiple recipients
• Error Handling - Handle errors gracefully
• Configuration - Configure the client
• Sending SMS - More SMS examples

Common Issues

"Unauthorized" Error

If you get an authorization error, check that:

• Your API key is correct
• The key is properly loaded from environment variables
• The key hasn't been revoked

"Invalid Phone Number" Error

Phone numbers must be in E.164 format:

• ✅ +256701521269 (correct)
• ❌ 0701521269 (missing country code)
• ❌ 256701521269 (missing + prefix)

See the Troubleshooting Guide for more help.