Library to send SMS messages to multiple recipients using Twilio API.
yarn add simple-sms-senderor
npm install --save simple-sms-senderimport { SmsSender } from 'simple-sms-sender';
const sender = new SmsSender({
accountSid: '', // string, required
fromNumber: '', // string, required
logger, // Logger instance, optional, defaults to console
secret: '', // string, required
sid: '' // string, required
});
// Returns a promise
sender.sendSms({
body: '', // string
recipients: [], // array of strings
scheduledTime: '' // optional ISO 8601 date string
});
sender.sendMultipleSms([
{ body: '', recipients: [] },
{ body: '', recipients: [], scheduledTime: '' }
]);import { SmsSender } from 'simple-sms-sender';
import pino from 'pino';
const logger = pino();
const config = {
accountSid: '{Your Twilio Account SID}',
fromNumber: '{Phone number to send}',
secret: '{Your Twilio Secret}',
sid: '{Your Twilio SID}'
};
const createSender = () => {
const { accountSid, fromNumber, secret, sid } = config;
return new SmsSender({
accountSid,
fromNumber,
logger, // optional
secret,
sid
});
};
const smsSender = createSender();
smsSender.sendMultipleSms([
{
body: 'Some message',
recipients: ['+19999999999', '+18888888888']
},
{
body: 'Some other message',
recipients: ['+19999999999']
},
{
body: 'Scheduled message',
recipients: ['+19999999999'],
scheduledTime: '2024-12-25T10:00:00Z' // Send on Christmas at 10 AM UTC
}
]);- Integration with Twilio API for SMS sending.
- Batch SMS sending to multiple recipients.
- Message scheduling - Schedule SMS messages up to 7 days in advance.
- Customizable logging with support for external logger instances.
- TypeScript support for type safety.
Before using this library, ensure you have:
- A Twilio account.
- Twilio Account SID, Auth Token (Secret), and SID.
- A phone number registered with Twilio for sending SMS.
| Parameter | Type | Required | Description |
|---|---|---|---|
| accountSid | string | Yes | Twilio Account SID |
| fromNumber | string | Yes | Phone number to send from |
| logger | GenericLogger | No | Logger instance, defaults to console |
| secret | string | Yes | Twilio Auth Token (Secret) |
| sid | string | Yes | Twilio SID |
body: string (required) — Message textrecipients: string[] (required) — List of phone numbersscheduledTime: string (optional) — ISO 8601 formatted date/time to schedule message delivery (up to 7 days in advance)- Returns:
Promise<any[]>
messages: Array<{ body: string, recipients: string[], scheduledTime?: string }>- Returns:
Promise<any[]>
You can schedule SMS messages to be sent at a future time using the scheduledTime parameter:
// Schedule a message for 1 hour from now
const futureTime = new Date(Date.now() + 60 * 60 * 1000);
smsSender.sendSms({
body: 'This message will be sent in 1 hour',
recipients: ['+19999999999'],
scheduledTime: futureTime.toISOString()
});
// Schedule a message for a specific date/time
smsSender.sendSms({
body: 'Happy New Year!',
recipients: ['+19999999999'],
scheduledTime: '2024-01-01T00:00:00Z'
});Scheduling Rules:
- Time must be in ISO 8601 format (e.g.,
2024-01-01T12:00:00Z) - Time must be in the future
- Maximum scheduling window is 7 days in advance
- Invalid formats or times will throw validation errors
- The
loggerparameter is optional. If not provided, logs will useconsole.logandconsole.error. - Logger must implement
{ info: (...args) => void, error: (...args) => void }.
smsSender.sendSms({
body: 'Hello!',
recipients: ['+19999999999']
}).catch(error => {
console.error('Failed to send SMS:', error);
});
smsSender.sendMultipleSms([
{ body: 'Message 1', recipients: ['+19999999999'] },
{ body: 'Message 2', recipients: ['+18888888888'] }
]).catch(error => {
console.error('Failed to send multiple SMS:', error);
});- Twilio Documentation for more details on Twilio API.
To run tests:
yarn testRelease versions follow Semantic Versioning.
To release a new version, ensure all tests pass and lint the code, then, make and push an empty commit like:
git commit --allow-empty -m "chore: release {release}" -m "Release-As: {release}"
# For example:
git commit --allow-empty -m "chore: release 0.3.0" -m "Release-As: 0.3.0"Release Please will automatically detect the commit message and create a new release based on the Release-As tag.
See CODE_STYLE.md for code style guidelines.
To lint the code:
yarn lintSee SECURITY.md for security policy and how to report vulnerabilities.
Contributions are welcome! Please open issues or pull requests.
See CHANGELOG.md for release history.
This project is licensed under the MIT License. See the LICENSE file for details.