Overview
Icon for SMSAPI

SMSAPI

Send SMS with optional test mode for safe messaging

Medusa v2 SMSAPI Plugin

A notification provider plugin that enables SMS notifications via SMSAPI.com and service for Medusa v2 projects.

Table of Contents

Features

  • SMS Notifications: Send SMS via SMSAPI.io service
  • Test Mode: Safe testing without sending actual SMS

Prerequisites

  • Medusa v2.4.0+
  • Node.js 20+
  • SMSAPI.io Account with API access token
  • Active SMS credits in your SMSAPI account

Installation

npm install @yanchesky/medusa-smsapi
# or
yarn add @yanchesky/medusa-smsapi

Configuration

1. Environment Variables

Create or update your Copy to clipboard.env file:

SMSAPI_ACCESS_TOKEN=your_smsapi_access_token_here
SMSAPI_FROM=YourBrand

2. Medusa Configuration

Add the plugin to your Copy to clipboardmedusa-config.ts:

import { SMSAPIOptions } from '@yanchesky/medusa-smsapi';
// ...
module.exports = {
// ... other configurations
modules: [
// ... other modules
{
resolve: '@yanchesky/medusa-smsapi/providers/smsapi',
dependencies: ['logger'] // Optional in test mode to log sent messages
options: {
channels: ['sms'], // Required: notification channels
access_token: process.env.SMSAPI_ACCESS_TOKEN,
from: process.env.SMSAPI_FROM,
} satisfies SMSAPIOptions,
},
],
}

Usage

Basic SMS Sending

import { Modules } from '@medusajs/framework/utils';
// ...
const notificationService = container.resolve(Modules.NOTIFICATION);
await notificationService.createNotifications([{
channel: 'sms',
to: '48123456789', // Country prefix is required
template: 'confrimation' // This is required by Medusa but is not used by the plugin.
content: {
text: "An SMS message"
}
}])

Configuration Options

SMSAPIOptions Interface

interface SMSAPIOptions {
// Required
access_token: string // Your SMSAPI access token
from: string // Sender name verified by SMSAPI
channels: string[] // Notification channels
// Optional Basic Settings
encoding?: string // Message encoding (default: "UTF-8")
test?: boolean // Test mode (default: false)
api_url?: string // API endpoint (default: "https://smsapi.io/api")
// Optional Advanced Settings
flash?: boolean // Flash SMS (default: false)
max_parts?: 1-10 // Maximum number of parts a message can be split into
nounicode?: boolean // Prevents from sending messages containing special characters.
normalize?: boolean // Converts special characters to regular ones. ฤ™ -> e; ฤ‡ -> c
fast?: boolean // Send SMS with the highest priority (default: false)
}

Test Mode

Enable test mode to validate your setup without sending actual SMS. In test mode a request to API endpoint will be executed validating credentials and logging sent message.

Local Development

# Run type checking
yarn typecheck
# Run linting
yarn lint
# Format code
yarn format
# Build plugin
yarn build

Contributing

All contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (Copy to clipboardgit checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run quality checks (Copy to clipboardyarn typecheck && yarn lint && yarn format:check)
  5. Commit your changes (Copy to clipboardgit commit -m 'Add amazing feature')
  6. Push to the branch (Copy to clipboardgit push origin feature/amazing-feature)
  7. Open a Pull Request

Development Guidelines

  • Follow existing code style and conventions
  • Add TypeScript types for all new features
  • Include comprehensive error handling
  • Update documentation for new features

Support

License

MIT License

Compatibility

  • โœ… Medusa: v2.4.0+
  • โœ… Node.js: 20+
  • โœ… TypeScript: 5+
  • โœ… OPEN API: Latest API version

You may also like

Browse all integrations

Build your own

Develop your own custom integraiton

Build your own integration with our API to speed up your processes. Make your integration available via npm for it to be shared in our Library with the broader Medusa community.

gift card interface

Ready to build your custom commerce setup?