An open-source Next.js application for sending and managing bulk SMS campaigns via the SMSPortal API.
- 📤 Bulk SMS Sending: Upload CSV files and send personalized messages to multiple recipients (up to 500 per batch)
- 📝 Message Templates: Use
{name}variable to personalize messages with recipient names - 💳 Credit Calculation: Automatic calculation of SMS credits (1 credit = 160 characters)
- 💰 Balance Tracking: View your SMSPortal account balance via API
- 📊 Campaign Management: Create, track, and manage SMS campaigns
- 📜 Message History: View and search through all sent messages
- 🎨 Modern UI: Clean and intuitive interface built with shadcn/ui components
- Node.js 18+ and npm
- SMSPortal API key (Get one here)
git clone <repository-url>
cd PulseSMSnpm installCopy the example environment file:
cp .env.local.example .env.localEdit .env.local and add your SMSPortal API key:
SMSPORTAL_API_KEY=your_api_key_herenpm run devOpen http://localhost:3000 in your browser.
The application expects CSV files with the following columns:
- name: Recipient's name (required)
- phone_number: Recipient's phone number (required)
The application will auto-detect column names, so variations like "phone", "mobile", "number" will also work.
name,phone_number
John Doe,+1234567890
Jane Smith,9876543210
Bob Johnson,+44123456789- Navigate to "Send Campaign" from the sidebar
- Enter a campaign name
- Upload a CSV file with recipients (name and phone_number columns)
- Write your message template using
{name}for personalization - Review the credit calculation
- Click "Send Campaign"
Use the {name} variable in your message template to personalize each message:
Hello {name}, welcome to our service!
This will be replaced with each recipient's name from the CSV file.
- 1 credit = 160 characters
- Credits are calculated per message and multiplied by the number of recipients
- The total credits needed for a campaign is displayed before sending
- Campaign History: View all campaigns with their status, recipient count, and credits used
- Campaign Details: Click on a campaign to see detailed information, progress, and individual message statuses
- Message History: View all messages across all campaigns with search and filter capabilities
PulseSMS/
├── app/
│ ├── campaigns/ # Campaign pages
│ ├── history/ # Message history page
│ └── api/ # API routes
├── components/
│ ├── campaigns/ # Campaign-related components
│ ├── messages/ # Message-related components
│ ├── sidebar/ # Sidebar navigation
│ └── ui/ # shadcn/ui components
├── lib/
│ ├── csv-parser.ts # CSV parsing logic
│ ├── credit-calculator.ts # Credit calculation
│ ├── smsportal.ts # SMSPortal API client
│ └── storage.ts # In-memory storage (replace with database)
└── types/
└── index.ts # TypeScript type definitions
- Framework: Next.js 16.1.1 (App Router)
- Language: TypeScript
- UI Components: shadcn/ui
- Icons: lucide-react
- CSV Parsing: papaparse
- Styling: Tailwind CSS
The application integrates with the SMSPortal API v3. All API calls are made server-side to keep your API key secure.
- API documentation: SMSPortal REST API v3
- Balance Endpoint: GET /v3/Balance - Retrieve account balance
- Bulk Messages Endpoint: POST /v3/BulkMessages - Send up to 500 messages per request
- The application automatically batches large campaigns (500 messages per batch)
- Authentication: Bearer token (API key) or Basic Auth (ClientID:APISecret)
npm run build
npm startnpm run lintCurrently, the application uses in-memory storage for campaigns and messages. This means data will be lost when the server restarts. For production use, replace the storage implementation in lib/storage.ts with a proper database (PostgreSQL, MongoDB, etc.).
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License - see LICENSE file for details.
For issues and questions, please open an issue on the GitHub repository.