Send SMS to North Macedonia: Complete 2025 Compliance & API Guide
Learn how to send SMS to North Macedonia with this comprehensive guide. Covers AEK regulations, GDPR compliance, alphanumeric sender IDs (no registration), Twilio/Sinch API integration, and Cyrillic encoding for 2M+ subscribers.
Learn how to send SMS messages to North Macedonia successfully while meeting AEK telecommunications regulations, GDPR data protection requirements, and technical specifications for A1 Macedonia and Makedonski Telekom networks. This comprehensive guide covers North Macedonia SMS compliance, alphanumeric sender ID setup (no pre-registration required), API integration with leading providers (Twilio, Sinch, MessageBird, Plivo), Cyrillic character encoding, and proven best practices for reaching over 2 million mobile subscribers effectively.
North Macedonia SMS Market Overview
Locale name:
North Macedonia
ISO code:
MK (retained from 2019 name change)
Region
Europe
Mobile country code (MCC)
294
Dialing Code
+389
Market Conditions: North Macedonia has a mature mobile market with high SMS adoption rates for business communications. The country's mobile network consists of two major operators: A1 Macedonia (formerly Vip, part of Telekom Austria group) with approximately 52% market share and Makedonski Telekom (part of Deutsche Telekom) with approximately 48% market share. Four MVNOs operate in the market with combined market share of just over 5%. Note: Lycamobile, previously an MVNO on the A1 network, was acquired by Mtel (Telekom Srbija) in November 2024 and is no longer operating independently. While OTT messaging apps like Viber and WhatsApp are popular, SMS remains crucial for business communications and authentication. Android devices dominate the market with approximately 85% market share compared to iOS at 15%. For SMS pricing details across providers, review the North Macedonia SMS pricing guide.
SMS Features and Technical Capabilities in North Macedonia
North Macedonia supports standard SMS features including concatenated messages and alphanumeric sender IDs. Two-way SMS functionality is limited through international providers.
Two-Way SMS Support
You cannot use two-way SMS in North Macedonia through most international SMS providers. If you need two-way functionality, contact carriers directly to establish local agreements.
Concatenated Messages (Segmented SMS)
Support: All major carriers support concatenation.
Message length rules:
GSM-7 encoding: 160 characters before splitting
UCS-2 encoding: 70 characters before splitting
Encoding considerations: Use GSM-7 for standard ASCII characters. Use UCS-2 for Cyrillic and special characters.
Example: A 200-character message in Cyrillic (UCS-2) splits into 3 segments:
Carriers automatically convert your MMS messages to SMS with an embedded URL link. This ensures delivery compatibility across all networks while allowing you to share rich media content via web links.
Recipient Phone Number Compatibility
Number Portability
Send SMS to ported numbers in North Macedonia without special configuration. Messages automatically route to the current carrier, so number portability does not impact your SMS delivery.
Sending SMS to Landlines
You cannot send SMS to landline numbers in North Macedonia. If you attempt to send SMS to a landline, your message will fail with a 400 response error (error code 21614) from most SMS APIs.
Validation tip: Use phone number validation APIs to detect landlines before sending:
TypeScript
// Example validation pattern for North Macedonia mobile numbersconst mobilePattern = /^389(7[0-9]|75|76|77|78)\d{6}$/;
North Macedonia SMS Compliance: AEK Regulations and GDPR Requirements
SMS communications in North Macedonia are regulated by the Agency for Electronic Communications (AEK) and must comply with the Law on Electronic Communications and the Law on Personal Data Protection (LPDP).
Regulatory Framework:
New Law on Electronic Communications: Adopted June 27, 2025 (Official Gazette No. 135/2025, July 4, 2025); effective June 1, 2026 (except data retention articles applying immediately)
Law on Personal Data Protection (LPDP): Adopted February 2020, enforceable from 2022; fully aligned with EU GDPR requirements
EU Candidacy: North Macedonia is aligning national legislation with EU standards as part of EU accession process
Data Protection Penalties: Up to 4% of company's total annual income for violations
The country follows GDPR-aligned data protection principles with requirements for consent management, data subject rights, breach notifications, and international data transfers. For businesses operating across the Balkans, also review Serbia SMS compliance and Albania SMS regulations requirements.
Consent and Opt-In Requirements
Obtain explicit consent before sending any marketing or promotional SMS messages. Follow these best practices:
Get written or electronic confirmation from recipients
Clearly disclose message frequency and content type
Maintain detailed consent records with timestamp and source
Use double opt-in confirmation for marketing lists
Refresh consent every 24 months
Compliant consent language example:
"I agree to receive promotional SMS from [Your Company] about [product category]. Message frequency: up to 4 messages per month. Reply STOP to opt out. Privacy policy: [URL]"
Non-compliant example (avoid):
"By using our service, you agree to receive messages" (too vague, lacks specificity)
Consequences: Non-compliance can result in fines up to 4% of annual revenue and damage to brand reputation.
HELP/STOP and Other Commands
Support these standard opt-out keywords in all your SMS campaigns:
STOP, CANCEL, END, QUIT
ПОМОШ (HELP in Macedonian)
СТОП (STOP in Macedonian)
Process messages in both Latin and Cyrillic alphabets. Provide response messages in both Macedonian and English.
Alphanumeric Sender ID and Phone Number Options for North Macedonia
Alphanumeric Sender ID
Operator network capability: Supported
Registration requirements: No pre-registration required – use dynamic sender IDs
Sender ID preservation: Yes, your sender IDs are preserved across all major networks
North Macedonia's no-registration policy for alphanumeric sender IDs makes it easier to send SMS compared to countries requiring pre-registration. For regional comparison, review Greece SMS requirements and Bulgaria SMS regulations.
Best practices for alphanumeric sender IDs:
Character limit: 11 characters maximum
Allowed characters: A-Z, a-z, 0-9 (no special characters or spaces)
Naming conventions: Use your brand name (e.g., "YourBank", "ShopName")
Brand recognition: Choose recognizable names that recipients will trust
Consistency: Use the same sender ID across all campaigns for brand consistency
Long Codes
Domestic vs. International:
Domestic long codes: Supported but unavailable for international providers
International long codes: Not supported by local networks
Sender ID preservation: No, carriers may replace international long codes with generic alphanumeric IDs
Provisioning time: 1–2 business days for domestic numbers
Use cases: Recommended for transactional messages and two-factor authentication
Short Codes
Support: Available through local carriers only
Provisioning time: 8–12 weeks for approval
Use cases: High-volume marketing campaigns, premium services, and emergency alerts
Restricted SMS Content, Industries, and Use Cases
Do not send SMS messages containing these restricted content categories:
Gambling and betting services
Adult content or services
Cryptocurrency promotions
Unauthorized financial services
Political campaign messages without proper disclosure
Political message disclosure requirements: Include the campaign sponsor name and registration number in every message. Example: "Vote for [Candidate]. Paid for by [Campaign Committee], Reg #12345"
Violation penalties: Fines range from €2,000 to €20,000 depending on severity and repeat offenses.
Content Filtering
Known carrier filtering rules:
Messages containing certain keywords in Macedonian or English
URLs from suspicious domains
High-frequency sending patterns
Avoid blocking by following these guidelines:
Avoid URL shorteners (bit.ly, tinyurl.com)
Use consistent sender IDs
Maintain regular sending patterns
Include clear business identification
Avoid excessive punctuation and all-caps
Best Practices for Sending SMS in North Macedonia
Messaging Strategy
Keep your messages under 160 characters when possible
Include clear calls-to-action
Personalize using the recipient's name or relevant details
Use proper character encoding for the Cyrillic alphabet
Include both Cyrillic and Latin scripts for critical information
Albanian-speaking regions: Primarily western municipalities including Tetovo, Gostivar, Debar, and Struga, representing approximately 25% of the population.
Translation best practices:
Hire native speakers for translation
Test messages with local focus groups
Avoid machine translation for marketing content
Use culturally appropriate idioms and references
Opt-Out Management
Process opt-outs within 24 hours
Send opt-out confirmation messages
Maintain opt-out lists across all campaigns
Regularly audit your opt-out processing
Testing and Monitoring
Test across both major carriers (A1 Macedonia, Makedonski Telekom) and MVNO networks
Monitor delivery rates by carrier
Track opt-out rates and patterns
Regularly test your opt-out functionality
Recommended KPIs to track:
Delivery rate: Target >95% for transactional, >90% for marketing
Bounce rate: Keep below 5%
Opt-out rate: Acceptable range 1–3% per campaign
Average response time: Track for two-way campaigns
Benchmark delivery rates by carrier:
A1 Macedonia: 96–98% (typical)
Makedonski Telekom: 95–97% (typical)
MVNOs: 93–96% (typical)
Troubleshooting common delivery issues:
Issue
Cause
Solution
High bounce rate
Invalid numbers
Validate numbers before sending
Low delivery rate
Carrier filtering
Review content for restricted keywords
Delayed delivery
Network congestion
Send during off-peak hours
Missing sender ID
Invalid format
Use 11-char alphanumeric limit
How to Integrate SMS APIs for North Macedonia
Twilio SMS Integration
Use Twilio's REST API to send SMS messages in North Macedonia. Authenticate with your Account SID and Auth Token.
TypeScript
import { Twilio } from'twilio';
// Initialize client with your credentialsconst client = newTwilio(
process.env.TWILIO_ACCOUNT_SID,
process.env.TWILIO_AUTH_TOKEN
);
// Send SMS to North MacedoniaasyncfunctionsendSMSToNorthMacedonia(to: string,
message: string,
senderId: string) {
try {
// Format number with +389 country codeconst formattedNumber = to.startsWith('+389') ? to : `+389${to}`;
const response = await client.messages.create({
body: message,
from: senderId, // Use alphanumeric sender ID (no registration required)to: formattedNumber,
statusCallback: 'https://your-webhook.com/status'// Track delivery status
});
return response.sid;
} catch (error) {
// Handle common North Macedonia-specific errorsif (error.code === 21614) {
console.error('Landline number not supported');
} elseif (error.code === 21408) {
console.error('Permission denied for this destination');
} elseif (error.code === 30006) {
console.error('Invalid sender ID format');
}
throw error;
}
}
// Implement retry logic with exponential backoffasyncfunctionsendWithRetry(to: string,
message: string,
senderId: string,
maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
returnawaitsendSMSToNorthMacedonia(to, message, senderId);
} catch (error) {
if (attempt === maxRetries - 1) throw error;
const delay = Math.pow(2, attempt) * 1000;
awaitnewPromise(resolve =>setTimeout(resolve, delay));
}
}
}
Sinch SMS Integration
Use Sinch's REST API for direct carrier connections in North Macedonia. Authenticate with your API Token.
Q: How long does it take for messages to be delivered?
A: Most messages deliver within 5–15 seconds. During peak hours or network congestion, delivery may take up to 2 minutes.
Q: Can I use the same sender ID for transactional and marketing messages?
A: Yes, but we recommend using different sender IDs to help recipients distinguish message types (e.g., "YourBank" for transactions, "YourBankAds" for marketing).
Q: What happens if a recipient's phone is turned off?
A: Messages are queued by the carrier for 24–72 hours. If the phone remains off, the message expires and you receive a failed delivery receipt.
Q: Do I need separate consent for transactional vs. marketing messages?
A: Transactional messages (order confirmations, OTPs) don't require marketing consent, but you still need agreement to your terms of service. Marketing messages require explicit opt-in consent.
Q: How do I handle messages that fail to deliver?
A: Implement retry logic with exponential backoff (3–5 attempts). If messages consistently fail to a number, remove it from your list and investigate the cause (invalid number, landline, blocked sender).
Frequently asked questions
SMS messages to Macedonia require using the +389 country code and adhering to local regulations. Explicit consent is mandatory for marketing messages, and standard opt-out keywords like STOP and HELP must be supported in both Latin and Cyrillic alphabets. Content restrictions apply to certain industries like gambling and adult content.
Plivo supports high-volume SMS sending in Macedonia. Use their messages.create API endpoint with the 'src' parameter for your sender ID, 'dst' for a comma-separated list of recipients, and 'text' for your message. Ensure compliance with Macedonian regulations for bulk sending.
Macedonia supports alphanumeric sender IDs without pre-registration. Sender ID preservation is maintained across major networks. This allows businesses to use their brand name as the sender, improving recognition and trust.
MMS messages are automatically converted to SMS with an embedded URL due to compatibility issues across all Macedonian networks. This ensures deliverability while still allowing for rich media sharing via the provided link.
Macedonia requires honoring opt-out requests within 24 hours. Businesses should send a confirmation of the opt-out, maintain opt-out lists across all campaigns, and regularly audit the process. Though no centralized registry exists, best practices include maintaining internal suppression lists.
Concatenated SMS is supported in Macedonia. The character limit is 160 for GSM-7 encoding and 70 for UCS-2 encoding. UCS-2 encoding is required for Cyrillic and special characters.
The best time to send SMS messages in Macedonia is between 9:00 AM and 8:00 PM local time, avoiding national holidays and respecting weekend quiet hours (before 10:00 AM and after 6:00 PM). Emergency messages are an exception to these timing restrictions.
No, sending SMS to landline numbers in Macedonia is not supported. Attempts to send SMS to landline numbers will result in delivery failure and a 400 response error (error code 21614) from most SMS APIs.
Several SMS API options are available for sending messages in Macedonia, including Twilio, Sinch, MessageBird, and Plivo. Each provider offers different features, pricing, and documentation for integrating their APIs.
Explicit consent is mandatory for marketing SMS in Macedonia, following EU-style data protection principles. You must support opt-out keywords like STOP, CANCEL, and HELP in both Latin and Cyrillic. The Agency for Electronic Communications (AEK) regulates SMS communications.
Keep messages under 160 characters, include clear calls to action, personalize content, and maintain a consistent sender ID. Adhering to these principles increases user engagement while adhering to technical limitations.
Avoid URL shorteners, use consistent sender IDs, maintain regular sending patterns, include clear business identification, and avoid excessive punctuation and all-caps. This helps prevent your messages from being flagged as spam.
The major mobile carriers in Macedonia are A1 Macedonia (formerly Vip), Makedonski Telekom, and Lycamobile. While OTT apps are popular, SMS remains essential for business communication.
Obtain consent through written or electronic confirmation, clearly disclosing message frequency and content. Maintain records with timestamps and the source of consent. Double opt-in and periodic consent refresh (every 24 months) are recommended best practices.
Learn how to send SMS messages to North Macedonia successfully while meeting AEK telecommunications regulations, GDPR data protection requirements, and technical specifications for A1 Macedonia and Makedonski Telekom networks. This comprehensive guide covers North Macedonia SMS compliance, alphanumeric sender ID setup (no pre-registration required), API integration with leading providers (Twilio, Sinch, MessageBird, Plivo), Cyrillic character encoding, and proven best practices for reaching over 2 million mobile subscribers effectively.
North Macedonia SMS Market Overview
Market Conditions: North Macedonia has a mature mobile market with high SMS adoption rates for business communications. The country's mobile network consists of two major operators: A1 Macedonia (formerly Vip, part of Telekom Austria group) with approximately 52% market share and Makedonski Telekom (part of Deutsche Telekom) with approximately 48% market share. Four MVNOs operate in the market with combined market share of just over 5%. Note: Lycamobile, previously an MVNO on the A1 network, was acquired by Mtel (Telekom Srbija) in November 2024 and is no longer operating independently. While OTT messaging apps like Viber and WhatsApp are popular, SMS remains crucial for business communications and authentication. Android devices dominate the market with approximately 85% market share compared to iOS at 15%. For SMS pricing details across providers, review the North Macedonia SMS pricing guide.
SMS Features and Technical Capabilities in North Macedonia
North Macedonia supports standard SMS features including concatenated messages and alphanumeric sender IDs. Two-way SMS functionality is limited through international providers.
Two-Way SMS Support
You cannot use two-way SMS in North Macedonia through most international SMS providers. If you need two-way functionality, contact carriers directly to establish local agreements.
Concatenated Messages (Segmented SMS)
Support: All major carriers support concatenation.
Message length rules:
Encoding considerations: Use GSM-7 for standard ASCII characters. Use UCS-2 for Cyrillic and special characters.
Example: A 200-character message in Cyrillic (UCS-2) splits into 3 segments:
Learn more about phone number formatting standards.
MMS Support
Carriers automatically convert your MMS messages to SMS with an embedded URL link. This ensures delivery compatibility across all networks while allowing you to share rich media content via web links.
Recipient Phone Number Compatibility
Number Portability
Send SMS to ported numbers in North Macedonia without special configuration. Messages automatically route to the current carrier, so number portability does not impact your SMS delivery.
Sending SMS to Landlines
You cannot send SMS to landline numbers in North Macedonia. If you attempt to send SMS to a landline, your message will fail with a 400 response error (error code 21614) from most SMS APIs.
Validation tip: Use phone number validation APIs to detect landlines before sending:
// Example validation pattern for North Macedonia mobile numbers const mobilePattern = /^389(7[0-9]|75|76|77|78)\d{6}$/;North Macedonia SMS Compliance: AEK Regulations and GDPR Requirements
SMS communications in North Macedonia are regulated by the Agency for Electronic Communications (AEK) and must comply with the Law on Electronic Communications and the Law on Personal Data Protection (LPDP).
Regulatory Framework:
The country follows GDPR-aligned data protection principles with requirements for consent management, data subject rights, breach notifications, and international data transfers. For businesses operating across the Balkans, also review Serbia SMS compliance and Albania SMS regulations requirements.
Consent and Opt-In Requirements
Obtain explicit consent before sending any marketing or promotional SMS messages. Follow these best practices:
Compliant consent language example: "I agree to receive promotional SMS from [Your Company] about [product category]. Message frequency: up to 4 messages per month. Reply STOP to opt out. Privacy policy: [URL]"
Non-compliant example (avoid): "By using our service, you agree to receive messages" (too vague, lacks specificity)
Consequences: Non-compliance can result in fines up to 4% of annual revenue and damage to brand reputation.
HELP/STOP and Other Commands
Support these standard opt-out keywords in all your SMS campaigns:
Process messages in both Latin and Cyrillic alphabets. Provide response messages in both Macedonian and English.
Code example for handling opt-out keywords:
function detectOptOut(message: string): boolean { const optOutKeywords = [ 'STOP', 'CANCEL', 'END', 'QUIT', 'UNSUBSCRIBE', 'СТОП', 'ОТКАЖИ', 'КРАЈ' ]; const normalizedMessage = message.toUpperCase().trim(); return optOutKeywords.some(keyword => normalizedMessage === keyword ); }Do Not Call / Do Not Disturb Registries
North Macedonia does not maintain a centralized Do Not Call registry. You must:
Time Zone Sensitivity
North Macedonia observes Central European Time (CET/CEST). Follow these timing guidelines:
North Macedonia national holidays to avoid:
Programmatic time zone detection:
import { DateTime } from 'luxon'; function isSendTimeAllowed(timezone = 'Europe/Skopje'): boolean { const now = DateTime.now().setZone(timezone); const hour = now.hour; const isWeekend = now.weekday >= 6; if (isWeekend) { return hour >= 10 && hour < 18; } return hour >= 9 && hour < 20; }Alphanumeric Sender ID and Phone Number Options for North Macedonia
Alphanumeric Sender ID
Operator network capability: Supported Registration requirements: No pre-registration required – use dynamic sender IDs Sender ID preservation: Yes, your sender IDs are preserved across all major networks
North Macedonia's no-registration policy for alphanumeric sender IDs makes it easier to send SMS compared to countries requiring pre-registration. For regional comparison, review Greece SMS requirements and Bulgaria SMS regulations.
Best practices for alphanumeric sender IDs:
Long Codes
Domestic vs. International:
Sender ID preservation: No, carriers may replace international long codes with generic alphanumeric IDs Provisioning time: 1–2 business days for domestic numbers Use cases: Recommended for transactional messages and two-factor authentication
Short Codes
Support: Available through local carriers only Provisioning time: 8–12 weeks for approval Use cases: High-volume marketing campaigns, premium services, and emergency alerts
Restricted SMS Content, Industries, and Use Cases
Do not send SMS messages containing these restricted content categories:
Political message disclosure requirements: Include the campaign sponsor name and registration number in every message. Example: "Vote for [Candidate]. Paid for by [Campaign Committee], Reg #12345"
Violation penalties: Fines range from €2,000 to €20,000 depending on severity and repeat offenses.
Content Filtering
Known carrier filtering rules:
Avoid blocking by following these guidelines:
Best Practices for Sending SMS in North Macedonia
Messaging Strategy
Sending Frequency and Timing
Optimal send times by day of week:
Industry benchmarks (average engagement rates):
Localization
Albanian-speaking regions: Primarily western municipalities including Tetovo, Gostivar, Debar, and Struga, representing approximately 25% of the population.
Translation best practices:
Opt-Out Management
Testing and Monitoring
Recommended KPIs to track:
Benchmark delivery rates by carrier:
Troubleshooting common delivery issues:
How to Integrate SMS APIs for North Macedonia
Twilio SMS Integration
Use Twilio's REST API to send SMS messages in North Macedonia. Authenticate with your Account SID and Auth Token.
import { Twilio } from 'twilio'; // Initialize client with your credentials const client = new Twilio( process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN ); // Send SMS to North Macedonia async function sendSMSToNorthMacedonia( to: string, message: string, senderId: string ) { try { // Format number with +389 country code const formattedNumber = to.startsWith('+389') ? to : `+389${to}`; const response = await client.messages.create({ body: message, from: senderId, // Use alphanumeric sender ID (no registration required) to: formattedNumber, statusCallback: 'https://your-webhook.com/status' // Track delivery status }); return response.sid; } catch (error) { // Handle common North Macedonia-specific errors if (error.code === 21614) { console.error('Landline number not supported'); } else if (error.code === 21408) { console.error('Permission denied for this destination'); } else if (error.code === 30006) { console.error('Invalid sender ID format'); } throw error; } } // Implement retry logic with exponential backoff async function sendWithRetry( to: string, message: string, senderId: string, maxRetries = 3 ) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { return await sendSMSToNorthMacedonia(to, message, senderId); } catch (error) { if (attempt === maxRetries - 1) throw error; const delay = Math.pow(2, attempt) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); } } }Sinch SMS Integration
Use Sinch's REST API for direct carrier connections in North Macedonia. Authenticate with your API Token.
import axios from 'axios'; class SinchSMSClient { private readonly apiToken: string; private readonly serviceId: string; constructor(apiToken: string, serviceId: string) { this.apiToken = apiToken; this.serviceId = serviceId; } async sendSMS(to: string, message: string) { const url = `https://sms.api.sinch.com/xms/v1/${this.serviceId}/batches`; try { const response = await axios.post( url, { from: 'YourBrand', // Use alphanumeric sender ID to: [to], body: message, encoding: 'AUTO' // Handles Cyrillic automatically }, { headers: { 'Authorization': `Bearer ${this.apiToken}`, 'Content-Type': 'application/json' } } ); return response.data.id; } catch (error) { console.error('Sinch SMS failed:', error); throw error; } } }MessageBird SMS Integration
Use MessageBird for reliable SMS delivery in North Macedonia with full Cyrillic character set support.
import { MessageBird } from 'messagebird'; class MessageBirdSMS { private client: MessageBird; constructor(apiKey: string) { this.client = new MessageBird(apiKey); } sendSMS( recipient: string, message: string, originator: string ): Promise<any> { return new Promise((resolve, reject) => { this.client.messages.create({ originator, // Maximum 11 characters for alphanumeric sender ID recipients: [recipient], body: message, datacoding: 'unicode' // Required for Cyrillic support }, (err, response) => { if (err) { reject(err); } else { resolve(response); } }); }); } }Plivo SMS Integration
Use Plivo for high-volume SMS campaigns in North Macedonia.
import * as plivo from 'plivo'; class PlivoSMSService { private client: plivo.Client; constructor(authId: string, authToken: string) { this.client = new plivo.Client(authId, authToken); } async sendBulkSMS( recipients: string[], message: string, senderId: string ) { try { const response = await this.client.messages.create({ src: senderId, dst: recipients.join('<'), // Plivo bulk sending format text: message, url_strip_query: false, method: 'POST' }); return response; } catch (error) { console.error('Plivo SMS failed:', error); throw error; } } }API Comparison Table:
API Rate Limits and Throughput
Default rate limits per provider:
Optimize large-scale sending with these strategies:
Practical implementation for rate limiting and queue management:
class SMSQueue { private queue: Array<{ to: string; message: string }> = []; private processing = false; private readonly rateLimit: number; // messages per second constructor(rateLimit: number = 50) { this.rateLimit = rateLimit; } async add(to: string, message: string) { this.queue.push({ to, message }); if (!this.processing) { await this.process(); } } private async process() { this.processing = true; const delayBetweenMessages = 1000 / this.rateLimit; while (this.queue.length > 0) { const item = this.queue.shift(); if (!item) break; try { await this.sendMessage(item.to, item.message); } catch (error) { // Re-queue failed messages this.queue.push(item); } await new Promise(resolve => setTimeout(resolve, delayBetweenMessages) ); } this.processing = false; } private async sendMessage(to: string, message: string) { // Your SMS API call here } }Exponential backoff implementation:
async function exponentialBackoff<T>( fn: () => Promise<T>, maxRetries: number = 5, baseDelay: number = 1000 ): Promise<T> { for (let attempt = 0; attempt < maxRetries; attempt++) { try { return await fn(); } catch (error) { if (attempt === maxRetries - 1) throw error; const delay = baseDelay * Math.pow(2, attempt); const jitter = Math.random() * 1000; await new Promise(resolve => setTimeout(resolve, delay + jitter) ); } } throw new Error('Max retries exceeded'); }Error Handling and Reporting
Implement comprehensive logging and monitor common error codes:
Common error codes for North Macedonia:
Webhook payload example for delivery receipts:
interface TwilioWebhook { MessageSid: string; MessageStatus: 'delivered' | 'failed' | 'undelivered'; To: string; From: string; ErrorCode?: string; ErrorMessage?: string; } app.post('/webhook/delivery', (req, res) => { const status: TwilioWebhook = req.body; if (status.MessageStatus === 'failed') { console.error('Message failed:', { sid: status.MessageSid, to: status.To, error: status.ErrorCode, message: status.ErrorMessage }); // Implement retry or alerting logic } res.sendStatus(200); });Automated alerting setup:
Store delivery receipts for compliance and troubleshooting. Recommended retention: 90 days minimum, 12 months for financial services.
Key Takeaways and Next Steps
What You've Learned
Your Next Steps
Getting started checklist (estimated timeline: 2–4 weeks):
Week 1: Setup and Compliance
Week 2: Integration
Week 3: Testing
Week 4: Launch and Monitor
Resource requirements:
Additional Resources
Industry Contacts:
Frequently Asked Questions
Q: How long does it take for messages to be delivered? A: Most messages deliver within 5–15 seconds. During peak hours or network congestion, delivery may take up to 2 minutes.
Q: Can I use the same sender ID for transactional and marketing messages? A: Yes, but we recommend using different sender IDs to help recipients distinguish message types (e.g., "YourBank" for transactions, "YourBankAds" for marketing).
Q: What happens if a recipient's phone is turned off? A: Messages are queued by the carrier for 24–72 hours. If the phone remains off, the message expires and you receive a failed delivery receipt.
Q: Do I need separate consent for transactional vs. marketing messages? A: Transactional messages (order confirmations, OTPs) don't require marketing consent, but you still need agreement to your terms of service. Marketing messages require explicit opt-in consent.
Q: How do I handle messages that fail to deliver? A: Implement retry logic with exponential backoff (3–5 attempts). If messages consistently fail to a number, remove it from your list and investigate the cause (invalid number, landline, blocked sender).