API Overview

The TextFlow API allows you to programmatically send SMS messages, manage contacts, and integrate TextFlow with your applications.

Base URL

All API requests should be made to:

https://textflow.telair.net/api

Authentication

The TextFlow API uses API keys for authentication. You must include your API key in every request using the X-API-Key header.

Getting Your API Key

1. Log in to your TextFlow account
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Give your key a descriptive name (e.g., “Production Integration”)
5. Choose environment: Production or Test
6. Copy the key immediately - it will only be shown once

API Key Formats

• Production keys: Start with sk_live_
• Test keys: Start with sk_test_

Keep Your API Keys Secret

Never share your API keys or commit them to version control. Treat them like passwords. If a key is compromised, revoke it immediately and generate a new one.

Using Your API Key

Include your API key in the X-API-Key header with every request:

curl -X POST https://textflow.telair.net/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "15551234567", "message": "Hello from TextFlow!"}'

Rate Limits

API requests are subject to rate limits based on your subscription plan:

Plan	Daily Limit	Per-Minute Limit
Starter	5,000	100
Marketer	25,000	300
Enterprise	Custom	Custom

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Response Format

All API responses are returned in JSON format with a consistent structure:

Success Response

{
  "success": true,
  "message": "Operation completed successfully",
  "data": {
    // Response data here
  }
}

Error Response

{
  "success": false,
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

Status Code	Meaning
200	Success - Request completed successfully
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing API key
403	Forbidden - API key doesn’t have permission for this action
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end

Common Error Messages

Error	Cause	Solution
API key required	Missing X-API-Key header	Add API key to request headers
Invalid API key format	Key doesn’t start with sk_live_ or sk_test_	Check that you copied the full key
Invalid or inactive API key	Key is revoked or doesn’t exist	Generate a new API key
Daily message limit reached	Account has hit daily sending limit	Upgrade plan or wait until next day
Invalid phone number format	Phone number is not in correct format	Use E.164 format: +1XXXXXXXXXX

Quick Start Example

Here’s a complete example of sending an SMS message using the API:

cURL

curl -X POST https://textflow.telair.net/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "message": "Hello! This is a test message from TextFlow."
  }'

Response

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "messageId": "msg_1234567890_abc123",
    "to": "+15551234567",
    "from": "+15559876543",
    "status": "sent"
  }
}

API Endpoints

The TextFlow API provides the following endpoints:

• Send SMS - Send individual SMS messages
• Manage Contacts - Create, update, and retrieve contacts (coming soon)
• Campaigns - Manage SMS campaigns (coming soon)

Security Best Practices

1. Rotate Keys Regularly: Generate new API keys every 90 days
2. Use Test Keys for Development: Never use production keys in development environments
3. Implement IP Whitelisting: If possible, restrict API access to known IP addresses
4. Monitor Usage: Regularly check API key usage in your dashboard
5. Revoke Compromised Keys: If a key is exposed, revoke it immediately

Testing Your Integration

Before going live:

1. Use a test API key (sk_test_*) for development
2. Test with your own phone number first
3. Verify error handling for common scenarios
4. Check that rate limiting is handled gracefully
5. Review all API responses for proper formatting

Getting Help

If you encounter issues with the API:

• Check the Troubleshooting Guide
• Review code examples
• Contact support at /support

Next Steps

• Send your first SMS message →
• View code examples →
• Learn about webhooks → (coming soon)