South Sudan SMS API Guide: Send SMS to +211 Numbers (MTN, Zain)

Send SMS messages to South Sudan (+211) using SMS APIs from Twilio, Sinch, Plivo, and Bird (MessageBird). This comprehensive guide covers everything you need to integrate SMS services in South Sudan: E.164 phone number formatting, MTN and Zain compliance requirements, sender ID pre-registration (3-week approval), character encoding limits, time zone considerations (UTC+3), and technical implementation for the South Sudan telecommunications market.

What Is the SMS Market Like in South Sudan?

Market Conditions: South Sudan's telecommunications market is dominated by three mobile operators: MTN South Sudan (59.7% market share with 3.3 million subscribers as of December 2024), Zain South Sudan, and Digitel Telecommunications. (Source: MTN South Sudan market data, verified January 2025)

Network Coverage & Penetration: As of early 2025, mobile penetration stands at 37.1% with 4.47 million cellular connections active – one of the lowest penetration rates in Africa. Network coverage is limited primarily to major towns, with 60.1% of the total population covered. (Source: DataReportal Digital 2025 South Sudan Report, verified March 2025) This makes SMS the most reliable business communication channel due to its universal reach across both urban and rural areas where internet and data services remain limited.

MTN-Specific Requirements: For the MTN network specifically, alphanumeric sender IDs require pre-registration and numeric international sender IDs are not supported – messages sent with numeric sender IDs will result in delivery failure. Avoid generic sender IDs like "InfoSMS," "INFO," "Verify," or "Notify" as these are blocked by MTN and other operators. (Source: Twilio South Sudan SMS Guidelines, verified January 2025)

What SMS Features Are Supported in South Sudan? (Two-Way, MMS, Concatenated SMS)

Two-way SMS

Two-way SMS (receiving replies) is not supported in South Sudan. You cannot receive inbound messages or process user responses to your outbound SMS campaigns.

Concatenated (Long) SMS

Concatenated SMS is not supported in South Sudan. Keep your messages under 160 characters (GSM-7 encoding) or 70 characters (Unicode) to ensure successful delivery. Messages exceeding these limits will be truncated or rejected.

Multimedia Messaging Service (MMS)

MMS is not supported in South Sudan. Send only text-based SMS messages. Attempts to send MMS will fail with error code 21408 (unrecognized message type).

How Do You Format South Sudan Phone Numbers?

E.164 Phone Number Format

Format South Sudan phone numbers according to the E.164 international standard:

• Format: +211XXXXXXXXX (country code +211 followed by 9 digits)
• Total length: 13 characters including the + symbol
• Example: +211912345678
• Always include the country code when you send SMS via API
• Omit leading zeros in the local number when using E.164 format

Note: South Sudan uses Mobile Country Code (MCC) 659. (Source: ITU-T E.164 standard, verified January 2025)

Number Portability

Number portability is not available in South Sudan. Mobile numbers remain tied to their original carrier, which simplifies your message routing but limits consumer flexibility in changing providers.

Sending SMS to Landlines

You cannot send SMS to landline numbers in South Sudan. Attempts to send messages to landline numbers will result in failed delivery and an error response (400 error code 21614) from the API. These messages will not appear in your logs, and your account will not be charged for failed attempts.

Character Encoding and Message Length

Character Encoding Limits:

• GSM-7 encoding: 160 characters (single SMS), 153 characters per segment (multi-part)
• UCS-2/Unicode encoding: 70 characters (single SMS), 67 characters per segment (multi-part)
• Messages exceeding these limits are automatically split into multiple segments
• Each segment counts as a separate SMS for billing purposes
• Use GSM-7 encoding when possible to maximize your character limits

What Are the SMS Compliance Requirements in South Sudan? (Consent, Sender ID, Content)

User Consent

Obtain explicit consent before you send SMS messages to recipients in South Sudan. Implement a clear opt-in process where users actively agree to receive your messages. Document consent timestamps and methods for compliance verification.

Compliant Opt-In Examples:

• Web form with checkbox: "I agree to receive SMS notifications from [Brand Name] at the number provided. Message frequency varies. Reply STOP to cancel."
• Double opt-in: After initial signup, send a confirmation SMS: "Reply YES to confirm subscription to [Brand Name] alerts. Msg&Data rates may apply."
• Point-of-sale consent: Document verbal consent with timestamp, customer number, and employee ID

Opt-Out Mechanism

Provide a clear, simple way for recipients to opt out of your SMS communications. Include opt-out instructions in your messages (e.g., "Reply STOP to unsubscribe"). Honor opt-out requests immediately and maintain a suppression list to prevent future messages to opted-out numbers.

Automated Opt-Out Implementation:

// Example suppression list management
const suppressionList = new Set();

function processInboundMessage(from, body) {
  const normalizedBody = body.trim().toUpperCase();

  if (['STOP', 'UNSUBSCRIBE', 'CANCEL', 'END', 'QUIT'].includes(normalizedBody)) {
    suppressionList.add(from);
    // Send confirmation
    sendSMS(from, "You have been unsubscribed. You will not receive further messages.");
    // Persist to database
    saveToDatabase(from, 'opted_out', new Date());
  }
}

function canSendTo(phoneNumber) {
  return !suppressionList.has(phoneNumber);
}

Time Restrictions

Avoid sending promotional SMS during late night or early morning hours. Recommended sending hours are 9:00 AM to 8:00 PM local time (UTC+3). Adjust your sending schedules to respect recipient time zones and cultural norms.

Time Zone Sensitivity

South Sudan observes UTC+3 (East Africa Time – EAT) year-round with no Daylight Saving Time changes. (Source: Standard East Africa Time zone, verified January 2025)

How Do You Register a Sender ID in South Sudan?

You can use alphanumeric sender IDs in South Sudan, but you must pre-register them with local carriers. Alphanumeric sender IDs (e.g., "YourBrand") display as the message sender instead of a phone number, improving brand recognition and trust.

Registration Requirements:

• Submit sender ID registration requests to your SMS provider
• Provide business documentation and use case details
• Allow 3 weeks for approval (MTN network specifically)
• Use only approved sender IDs for your campaigns

Required Documentation:

• Business registration certificate or incorporation documents
• Sender name (3–11 alphanumeric characters, no spaces recommended)
• Sample message content demonstrating intended use
• Company website URL
• Traffic type classification (transactional, informational, or marketing)
• Contact information for authorized representative

Common Rejection Reasons:

• Generic sender IDs (InfoSMS, INFO, Verify, Notify, Alert)
• Sender IDs that impersonate government agencies or banks
• Promotional content submitted for transactional sender IDs
• Incomplete or unverified business documentation
• Sender IDs containing special characters or spaces

Fallback Strategy: During the registration period or if registration fails, use an international long code as your sender ID. Note that numeric international sender IDs are not supported on the MTN network – messages will fail delivery. (Source: Twilio South Sudan SMS Guidelines, verified January 2025)

Content Restrictions

South Sudan restricts certain types of SMS content. Avoid sending:

• Person-to-Person (P2P) messages: Use only Application-to-Person (A2P) messaging for business communications
• Adult content: Prohibited under local regulations
• Religious or political content: Subject to strict scrutiny and potential blocking
• Misleading or fraudulent content: Results in immediate suspension

Violating content restrictions can result in message blocking, account suspension, or legal penalties. Review your message content carefully before you launch campaigns. (Source: Clickatell South Sudan SMS Regulations, verified January 2025)

How Much Does It Cost to Send SMS in South Sudan? (Twilio, Sinch, Plivo Pricing)

SMS pricing varies by provider and message volume. Contact providers directly for current rates and volume discounts.

Important: SMS pricing changes frequently. Always verify current rates with your chosen provider before you deploy production campaigns. Consider these factors:

• Message volume commitments for discounts
• Currency conversion rates
• Additional fees for premium features
• Sender ID registration costs (one-time or annual fees may apply)

How to Integrate SMS APIs for South Sudan (Twilio, Sinch, Plivo, MessageBird)

API Rate Limits & Throttling: Be aware of provider-specific rate limits to avoid throttling:

• Twilio: 10 message segments per second (MPS) for international destinations; account-level concurrency limit applies (HTTP 429 errors when exceeded). Messages queue for up to 10 hours based on MPS rate. (Source: Twilio Rate Limits Guide, verified January 2025)
• Sinch: Rate limits vary by service plan; messages queue in FIFO order per service plan. Check your plan documentation for specific MPS limits. (Source: Sinch SMS Rate Limits, verified January 2025)
• Plivo: Default limit of 300 API requests per 5 seconds; outbound MPS limit of 5 for SMS by default (can be increased upon request). (Source: Plivo Account Limits, verified January 2025)

Testing Strategy: Before production deployment:

1. Use provider sandbox/test environments where available
2. Test with a small group of internal phone numbers first
3. Verify sender ID display on actual South Sudan mobile devices (MTN, Zain)
4. Test error handling with invalid numbers and unsupported formats
5. Monitor delivery rates and adjust retry logic as needed

Security Note: Never commit API credentials to version control. Add .env to your .gitignore file:

# Add to .gitignore
.env
.env.local
.env.*.local

Additional Security Best Practices:

• Credential rotation: Rotate API keys every 90 days or immediately if compromised
• IP whitelisting: Restrict API access to known server IP addresses where supported
• Webhook signature verification: Validate delivery receipt webhooks using HMAC signatures
• Least privilege access: Use separate API keys for development, staging, and production
• Audit logging: Log all API requests with timestamps for security monitoring

Twilio

Twilio provides reliable SMS delivery to South Sudan through their REST API. Here's how to implement it:

npm install twilio

const twilio = require('twilio');

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = twilio(accountSid, authToken);

client.messages
  .create({
    body: "Your message here",
    from: "YourBrand",      // Pre-registered alphanumeric sender ID
    to: "+211912345678",    // South Sudan number in E.164 format
    statusCallback: "https://yourserver.com/sms/status" // Delivery receipt webhook
  })
  .then(message => {
    console.log(`Message sent: ${message.sid}`);
    console.log(`Status: ${message.status}`); // queued, sent, delivered, failed
  })
  .catch(error => console.error("Error:", error));

Twilio Message Status Codes:

• queued: Message accepted and queued for delivery
• sending: Message is being sent to carrier
• sent: Message sent to carrier (not yet delivered to device)
• delivered: Message successfully delivered to recipient device
• undelivered: Message failed to deliver (check error code)
• failed: Message rejected (invalid number, unsupported format, or blocked content)

Webhook Implementation for Delivery Receipts:

const express = require('express');
const app = express();

app.post('/sms/status', express.urlencoded({ extended: false }), (req, res) => {
  const { MessageSid, MessageStatus, ErrorCode } = req.body;

  console.log(`Message ${MessageSid} status: ${MessageStatus}`);

  if (MessageStatus === 'failed' || MessageStatus === 'undelivered') {
    console.error(`Delivery failed. Error code: ${ErrorCode}`);
    // Handle failure: retry, alert, or update database
  }

  res.status(200).send('OK');
});

Sinch

Sinch offers SMS connectivity to South Sudan with detailed delivery analytics:

npm install @sinch/sdk-core

const { SinchClient } = require('@sinch/sdk-core');
const { Sms } = require('@sinch/sdk-sms');

const client = new SinchClient({
  projectId: process.env.SINCH_PROJECT_ID,
  keyId: process.env.SINCH_KEY_ID,
  keySecret: process.env.SINCH_KEY_SECRET,
});

const smsService = client.sms();

smsService.batches.send({
  to: ["+211912345678"], // South Sudan number in E.164 format
  from: "YourBrand",      // Pre-registered sender ID
  body: "Your message here",
  delivery_report: "per_recipient" // Request delivery reports
})
.then(response => console.log("Message sent:", response))
.catch(error => console.error("Error:", error));

MessageBird

Note: MessageBird rebranded to Bird in 2022. The messagebird npm package may be deprecated. Verify the current SDK at Bird.com or check the MessageBird npm package for the latest integration approach.

MessageBird provides SMS connectivity to South Sudan with detailed delivery reporting:

npm install messagebird

const messagebird = require('messagebird');

const client = messagebird(process.env.MESSAGEBIRD_ACCESS_KEY);

client.messages.create({
  originator: "YourBrand",  // Pre-registered sender ID
  recipients: ["+211912345678"], // South Sudan number in E.164 format
  body: "Your message here"
}, (err, response) => {
  if (err) {
    console.error("Error:", err);
  } else {
    console.log("Message sent:", response);
  }
});

Plivo

Plivo delivers SMS to South Sudan with comprehensive API features:

npm install plivo

const plivo = require('plivo');

const client = new plivo.Client(
  process.env.PLIVO_AUTH_ID,
  process.env.PLIVO_AUTH_TOKEN
);

client.messages.create(
  "YourBrand",      // Pre-registered sender ID
  "+211912345678",  // South Sudan number in E.164 format
  "Your message here"
)
.then(response => console.log("Message sent:", response))
.catch(error => console.error("Error:", error));

What Are the Best Practices for Sending SMS in South Sudan? (Delivery, Timing, Content)

Message Content

• Keep your messages concise and under 160 characters
• Use clear, simple language that your audience understands
• Avoid special characters that might not display correctly
• Include your brand name or identifier for recognition
• Provide clear calls-to-action (e.g., "Visit our store," "Reply YES")

Delivery Optimization

• Send messages during business hours (9:00 AM – 8:00 PM UTC+3)
• Avoid peak network congestion times (typically 8:00 AM – 9:00 AM, 5:00 PM – 6:00 PM)
• Implement retry logic with exponential backoff for failed deliveries
• Monitor delivery rates and adjust your sending strategy accordingly

Retry Logic with Exponential Backoff:

async function sendWithRetry(to, body, maxRetries = 3) {
  let delay = 1000; // Start with 1 second delay

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const message = await client.messages.create({
        body: body,
        from: "YourBrand",
        to: to
      });

      console.log(`Message sent successfully: ${message.sid}`);
      return message;
    } catch (error) {
      if (attempt === maxRetries) {
        console.error(`Failed after ${maxRetries} attempts:`, error);
        throw error;
      }

      // Retry on temporary errors (rate limits, network issues)
      if (error.code === 20429 || error.status >= 500) {
        console.log(`Attempt ${attempt} failed. Retrying in ${delay}ms…`);
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= 2; // Exponential backoff: 1s, 2s, 4s
      } else {
        // Don't retry permanent errors (invalid number, blocked content)
        throw error;
      }
    }
  }
}

Message Queuing for High-Volume Sending:

const Bull = require('bull');
const smsQueue = new Bull('sms-queue', {
  redis: { host: 'localhost', port: 6379 }
});

// Add messages to queue
smsQueue.add({ to: '+211912345678', body: 'Your message' }, {
  attempts: 3,
  backoff: { type: 'exponential', delay: 2000 }
});

// Process queue with rate limiting
smsQueue.process(5, async (job) => { // Process 5 messages concurrently
  const { to, body } = job.data;
  return await client.messages.create({ to, body, from: 'YourBrand' });
});

Error Handling

Implement robust error handling in your application:

client.messages.create({
  body: "Your message here",
  from: "YourBrand",
  to: "+211912345678"
})
.then(message => {
  console.log(`Success: ${message.sid}`);
  // Log success metrics
})
.catch(error => {
  // Twilio/Plivo error codes
  if (error.code === 21614) {
    console.error("Invalid recipient number (landline or incorrect format)");
  } else if (error.code === 21408) {
    console.error("Message type not supported (MMS not available)");
  } else if (error.code === 21610) {
    console.error("Message blocked: unregistered sender ID or prohibited content");
  } else if (error.code === 20429) {
    console.error("Rate limit exceeded: implement backoff and retry");
  } else if (error.code === 21211) {
    console.error("Invalid \"To\" phone number: verify E.164 format");
  } else if (error.code === 21212) {
    console.error("Invalid \"From\" sender ID: verify pre-registration status");
  } else {
    console.error("Delivery failed:", error.message, "Code:", error.code);
  }
});

Common Error Codes & Troubleshooting:

• 21614: Landline number or SMS not supported on this number type → Verify recipient has mobile number
• 21408: MMS not supported → Send text-only SMS
• 21610: Message blocked by carrier → Check sender ID registration and content compliance
• 20429: Too many requests → Implement rate limiting and exponential backoff
• 21211: Invalid "To" number → Validate E.164 format (+211 + 9 digits)
• 21212: Invalid "From" sender → Verify sender ID is pre-registered and approved
• 30006: Carrier rejected message → Contact carrier for specific rejection reason
• 30007: Message filtered by carrier → Review content for restricted keywords or format issues

Monitoring and Analytics

Track these key metrics for your SMS campaigns:

• Delivery rate: Percentage of successfully delivered messages
• Failure rate: Percentage of failed deliveries with error codes
• Response time: Average time between send and delivery
• Opt-out rate: Percentage of recipients who unsubscribe
• Engagement rate: For campaigns with tracked links or codes

Acceptable Benchmarks:

• Delivery rate: Target ≥95% for transactional, ≥90% for promotional
• Failure rate: Investigate if >5% (indicates data quality or routing issues)
• Average delivery time: Expect 5–30 seconds for successful delivery
• Opt-out rate: <2% is normal; >5% suggests poor targeting or frequency issues

Implementation Example for Tracking Metrics:

const metrics = {
  sent: 0,
  delivered: 0,
  failed: 0,
  optedOut: 0
};

async function sendAndTrack(to, body) {
  try {
    const message = await client.messages.create({ to, body, from: "YourBrand" });
    metrics.sent++;

    // Track delivery via webhook or polling
    setTimeout(async () => {
      const status = await client.messages(message.sid).fetch();
      if (status.status === 'delivered') {
        metrics.delivered++;
      } else if (status.status === 'failed' || status.status === 'undelivered') {
        metrics.failed++;
      }
    }, 60000); // Check after 1 minute

    return message;
  } catch (error) {
    metrics.failed++;
    throw error;
  }
}

// Generate report
function getMetrics() {
  const deliveryRate = (metrics.delivered / metrics.sent * 100).toFixed(2);
  const failureRate = (metrics.failed / metrics.sent * 100).toFixed(2);
  console.log(`Delivery Rate: ${deliveryRate}% | Failure Rate: ${failureRate}%`);
}

Regulatory Compliance

• Maintain records of user consent for at least 2 years
• Update your suppression list immediately when users opt out
• Review message content for compliance with local restrictions
• Register sender IDs before you launch campaigns (allow 3 weeks for MTN network)
• Consult legal experts for regulatory interpretation

How Do You Troubleshoot Common SMS Issues in South Sudan?

Issue: Messages not delivering to MTN network

Symptoms: Messages return "failed" or "undelivered" status specifically for MTN numbers

Solutions:

1. Verify sender ID is pre-registered with MTN (alphanumeric required, numeric not supported)
2. Avoid generic sender IDs (InfoSMS, INFO, Verify, Notify)
3. Check message content for restricted keywords (political, religious, adult content)
4. Confirm phone number format is correct E.164: +211XXXXXXXXX

Issue: High rate of error code 20429 (rate limit exceeded)

Symptoms: Multiple messages failing with "Too Many Requests" errors

Solutions:

1. Implement message queuing system (Bull, RabbitMQ, or AWS SQS)
2. Add exponential backoff retry logic
3. Reduce concurrent API requests (stay under 10 MPS for international destinations)
4. Consider purchasing additional phone numbers for higher throughput (not recommended for US/Canada destinations)

Issue: Sender ID not displaying as expected

Symptoms: Recipients see different sender ID than what was sent

Solutions:

1. Wait for sender ID registration approval (3 weeks for MTN)
2. Use alphanumeric sender ID 3–11 characters without spaces
3. Verify sender ID is approved for specific traffic type (transactional vs. marketing)
4. During registration period, use pre-approved sender ID or international long code

Issue: Messages truncated or split unexpectedly

Symptoms: Recipients receive partial messages or multiple SMS segments

Solutions:

1. Keep messages under 160 characters for GSM-7 encoding
2. Use only GSM-7 character set (avoid emojis, special Unicode characters)
3. Remember concatenated SMS is not supported in South Sudan – excess characters are truncated
4. Test messages with segment calculator tools before sending

Next Steps

1. Technical Implementation

• Choose your SMS provider based on pricing and features
• Set up your development environment with API credentials
• Implement error handling and retry logic with exponential backoff
• Test with a small user group before full deployment

2. Compliance

• Review local regulations and carrier requirements (especially MTN-specific rules)
• Document your consent processes and retention policies
• Set up automated opt-out handling with suppression list
• Consult legal experts for regulatory guidance

3. Operations

• Create a monitoring dashboard for delivery metrics (target ≥95% delivery rate)
• Set up alerting for delivery failures or anomalies (>5% failure rate)
• Develop escalation procedures for critical issues
• Train your support team on SMS operations and common troubleshooting steps

Additional Resources

Technical Standards:

• ITU-T E.164 Numbering Resources – International phone number format specifications
• GSMA International SMS Best Practices – Global mobile industry standards and guidelines

South Sudan Carriers:

• MTN South Sudan – Dominant mobile operator in South Sudan (59.7% market share)

Provider Guidelines:

• Twilio South Sudan SMS Guidelines – Official Twilio compliance requirements
• Clickatell South Sudan SMS Regulations – Content restrictions and regulations

Related SMS Guides:

• E.164 Phone Number Formatting Standards – Learn international phone number formatting
• SMS API Comparison: Twilio vs Sinch vs Plivo vs MessageBird – Compare features and pricing
• International SMS Compliance by Country – Global SMS regulations