Skip to main content
Number Pool automatically distributes your outbound messages across multiple phone numbers, helping you scale messaging campaigns while maintaining deliverability. Instead of specifying a single “from” number, Telnyx selects the optimal sender from your pool based on availability, health, and configured weights.

​
When to Use Number Pool

High Volume Campaigns

Distribute traffic across numbers to avoid per-number rate limits and increase total throughput.

Improved Deliverability

Automatically skip unhealthy numbers and spread reputation across multiple senders.

Mixed Number Types

Balance between long codes and toll-free numbers with configurable weights.

Simplified Sending

No need to track which number to use—Telnyx handles sender selection.

​
How It Works

  1. Pool creation: All long code and toll-free numbers assigned to your Messaging Profile form the pool
  2. Sender selection: When you send a message, Telnyx picks an available number from the pool
  3. Weight distribution: Control the ratio of long code vs. toll-free usage with weights
  4. Health monitoring: Optionally skip numbers with poor delivery rates

​
Prerequisites

  • A Messaging Profile with at least one phone number assigned
  • Multiple numbers recommended for effective load distribution

​
Configure Number Pool

Enable Number Pool on your Messaging Profile by setting the number_pool_settings. The weights control which number types are preferred. 
curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "number_pool_settings": {
      "long_code_weight": 5,
      "toll_free_weight": 1,
      "skip_unhealthy": true
    }
  }'

​
Configuration Options

ParameterTypeDescription
long_code_weightintegerWeight for long code selection (0 removes from pool)
toll_free_weightintegerWeight for toll-free selection (0 removes from pool)
skip_unhealthybooleanSkip numbers with poor delivery rates
sticky_senderbooleanReuse same number for recipient when possible
geomatchbooleanMatch sender to recipient’s geographic area
Weights are ratios, not percentages. With long_code_weight: 5 and toll_free_weight: 1, approximately 5 out of every 6 messages use a long code.

​
Send Messages with Number Pool

When sending with Number Pool, omit the from field and specify your messaging_profile_id instead. Telnyx automatically selects the optimal sender. 
curl -X POST "https://api.telnyx.com/v2/messages/number_pool" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "messaging_profile_id": "YOUR_PROFILE_ID",
    "to": "+15559876543",
    "text": "Hello from Number Pool!"
  }'
The response includes the actual from number that was selected: 
{
  "data": {
    "id": "b0c7e8cb-6227-4c74-9f32-c7f80c30934b",
    "type": "SMS",
    "from": {
      "phone_number": "+15551234567",
      "carrier": "Telnyx",
      "line_type": "long_code"
    },
    "to": [
      {
        "phone_number": "+15559876543",
        "status": "queued"
      }
    ],
    "text": "Hello from Number Pool!"
  }
}

​
Disable Number Pool

To disable Number Pool, set number_pool_settings to an empty object: 
curl -X PATCH "https://api.telnyx.com/v2/messaging_profiles/YOUR_PROFILE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number_pool_settings": {}}'
Number Pool works alongside these Messaging Profile features:
Maintains consistency by using the same number for a recipient across messages. When enabled, if you’ve previously messaged a recipient, the same number is reused when available.Enable with:
{
  "number_pool_settings": {
    "long_code_weight": 1,
    "sticky_sender": true
  }
}
See Sticky Sender for details.
Selects a sender number matching the recipient’s geographic area, improving deliverability and user trust by showing a local number.Enable with:
{
  "number_pool_settings": {
    "long_code_weight": 1,
    "geomatch": true
  }
}
See Geomatch for details.
Monitors delivery success rates and automatically excludes numbers performing poorly. This helps maintain overall campaign deliverability.
If all numbers in the pool are unhealthy, message sending will fail rather than use an unhealthy number.

​
Troubleshooting

Cause: All numbers are flagged as unhealthy and skip_unhealthy is enabled.Solutions:
  1. Temporarily disable skip_unhealthy to allow sending
  2. Add more numbers to your Messaging Profile
  3. Investigate delivery issues on your existing numbers
Cause: Weight of one type set to 0, or only one number type assigned.Solutions:
  1. Verify weights are non-zero for both types
  2. Ensure you have both long codes and toll-free numbers assigned to the profile
Cause: Using the standard /v2/messages endpoint instead of /v2/messages/number_pool.Solution: Use the Number Pool send endpoint which requires messaging_profile_id instead of from.

​
Next Steps

Sticky Sender

Maintain sender consistency for recipients

Geomatch

Match sender to recipient geography

Rate Limiting

Understand messaging throughput limits

API Reference

View full Number Pool API details