Connect Business Messaging with the TextTorrent SMS API

Developers can use verified TextTorrent REST endpoints to connect business SMS workflows with their applications. Authenticate with API credentials, send supported SMS or MMS messages, retrieve conversation and campaign status data, and process inbound replies through documented API retrieval patterns.

TextTorrent SMS API documentation showing an authenticated message request and response

No credit card required

Send Messages from Your Application

Retrieve Messaging Activity

Connect Operational Workflows

The Challenge

Business Messaging Should Connect with Existing Software

Teams often need text messaging to start from application events, return status to business systems, and keep replies connected to the right operational workflow.

Manual Sending Does Not Scale Across Systems

Manual Sending Does Not Scale Across Systems

Teams may need messages triggered from CRM, application, or operational activity instead of only from a manual composer.

Delivery Results Need to Return to the Application

Delivery Results Need to Return to the Application

Systems need verified message identifiers and status records to update workflows after a send attempt.

Customer Replies Need a Clear Destination

Customer Replies Need a Clear Destination

Inbound responses should connect to contact records, inbox conversations, or internal processes.

Messaging Rules Must Remain Consistent

Messaging Rules Must Remain Consistent

API-based messaging must still respect registration, consent, opt-outs, credits, and number configuration.

The TextTorrent Developer Workflow

Connect Requests, Messaging Events, and Business Records

The TextTorrent API connects your application to authentication, SMS or MMS requests, sending numbers, campaign or inbox workflows, message identifiers, status records, contacts, Claims, analytics, and sub-account scope where supported.

TextTorrent SMS API integration flow from application request to message status and inbound reply
Applications authenticate, submit messaging requests, then retrieve status and conversation updates through verified API endpoints.
  1. Application
  2. TextTorrent API
  3. Messaging workflow
  4. Provider or carrier
  5. Status or reply record
  6. Application
How It Works

How to Connect an Application to the TextTorrent API

Use a clear sequence so credentials, documentation, test sends, identifiers, and reply handling stay connected.

01

Create or Locate an API Key

Find your Account SID and Public API Key in your TextTorrent account settings or API dashboard. Credentials are generated when the account is created.

02

Review the API Documentation

Confirm the base URL https://api.texttorrent.com, the /api/v1 prefix, endpoint method, required fields, and response envelope.

03

Prepare a Test Request

Use approved internal or test contacts and an active sending number before integrating production audiences.

04

Send the Request

Submit an authenticated request through a verified endpoint such as POST /api/v1/inbox/chat or POST /api/v1/campaigning/bulk.

05

Store the Returned Identifier

Store the message id, msg_sid, campaign_id, or other identifier returned in the success response.

06

Retrieve Status Updates

Use campaign analytics message logs, inbox conversation endpoints, or credit logs to review later activity. Documented push webhook event catalogs are not currently published.

07

Handle Replies and Errors

Read inbound replies through inbox APIs and Claims workflows, and handle validation, credit, or authentication errors using the documented response envelope.

  1. Create key
  2. Review docs
  3. Send test
  4. Store ID
  5. Retrieve status
  6. Handle reply or error
Authentication

Protect API Credentials and Limit Access

TextTorrent API requests use API-key authentication. Include both X-API-SID and X-API-PUBLIC-KEY on every request. Unauthenticated requests receive 401 Unauthorized.

Required headers

X-API-SID
Your Account SID.
X-API-PUBLIC-KEY
Your Public API Key.
X-ACT-AS-USER
Optional. Parent accounts may act as an active sub-account by supplying that sub-account’s email.
Header example
X-API-SID: SID....................................
X-API-PUBLIC-KEY: PK.....................................
Content-Type: application/json
Accept: application/json
  • Store keys in server-side environment variables.
  • Never expose keys in browser code.
  • Do not commit keys to source control.
  • Rotate compromised keys.
  • Restrict user access to key management.
  • Redact keys from logs and screenshots.
  • Remove access when an integration is retired.

Scoped keys, automatic expiration, and dedicated key-rotation UI controls are not claimed unless confirmed in the current account interface.

Read authentication in the API documentation

TextTorrent API key management screen with the secret value redacted
Outbound SMS

Send Business Text Messages Through a Verified API Endpoint

Send an SMS or MMS message to a contact in an existing conversation with POST /api/v1/inbox/chat. Use multipart/form-data and an active sending number from your account.

POST/api/v1/inbox/chat

Content-Type: multipart/form-data

Request fields for /api/v1/inbox/chat
FieldTypeRequiredDescription
messagestringYesMessage content (max 5000 characters).
chat_idintegerYesID of the conversation thread.
from_numberstringYesSender phone number that exists in your active numbers.
to_numberstringYesRecipient phone number.
chatFilefileNoOptional media attachment for MMS (image, video, or audio).
cURL
curl -X POST "https://api.texttorrent.com/api/v1/inbox/chat" \
  -H "X-API-SID: SID...................................." \
  -H "X-API-PUBLIC-KEY: PK....................................." \
  -H "Accept: application/json" \
  -F "message=Hello! How can I help you today?" \
  -F "chat_id=1234" \
  -F "from_number=+12025559999" \
  -F "to_number=+12025551234"
JavaScript
async function sendMessage(chatId, message, fromNumber, toNumber) {
  const formData = new FormData();
  formData.append("message", message);
  formData.append("chat_id", String(chatId));
  formData.append("from_number", fromNumber);
  formData.append("to_number", toNumber);

  const response = await fetch(
    "https://api.texttorrent.com/api/v1/inbox/chat",
    {
      method: "POST",
      headers: {
        "X-API-SID": process.env.TEXTTORRENT_SID,
        "X-API-PUBLIC-KEY": process.env.TEXTTORRENT_PUBLIC_KEY,
        Accept: "application/json",
      },
      body: formData,
    },
  );

  const data = await response.json();
  if (!data.success) {
    throw new Error(data.message || "Unable to send message");
  }
  return data.data;
}
PHP
$ch = curl_init("https://api.texttorrent.com/api/v1/inbox/chat");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-SID: " . getenv("TEXTTORRENT_SID"),
    "X-API-PUBLIC-KEY: " . getenv("TEXTTORRENT_PUBLIC_KEY"),
    "Accept: application/json",
  ],
  CURLOPT_POSTFIELDS => [
    "message" => "Hello! How can I help you today?",
    "chat_id" => 1234,
    "from_number" => "+12025559999",
    "to_number" => "+12025551234",
  ],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
if (empty($data["success"])) {
  throw new RuntimeException($data["message"] ?? "Unable to send message");
}
Success response
{
  "code": 201,
  "success": true,
  "message": "Message send successfully",
  "data": {
    "id": 5002,
    "chat_id": 1234,
    "direction": "outbound",
    "message": "Hello! How can I help you today?",
    "msg_type": "sms",
    "file": null,
    "api_send_status": "sent",
    "msg_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2025-10-17T15:30:00.000000Z",
    "updated_at": "2025-10-17T15:30:05.000000Z"
  },
  "errors": null
}
Validation error
{
  "code": 422,
  "success": false,
  "message": "Validation Error",
  "data": null,
  "errors": {
    "message": ["The message field is required."],
    "from_number": ["The selected from number is invalid."],
    "chat_id": ["The chat id field is required."],
    "to_number": ["The to number field is required."]
  }
}

To start a new conversation, use POST /api/v1/inbox/chat/create with receiver_number and sender_id before sending into an existing chat_id.

TextTorrent send SMS API endpoint with request parameters and response example

Open the complete endpoint documentation

Bulk Messaging

Create Larger Messaging Workflows Through Supported API Operations

Create SMS or MMS campaigns with POST /api/v1/campaigning/bulk. Campaigns reference a contact list, template, message body, and one or more sending numbers.

POST/api/v1/campaigning/bulk

Required fields

  • campaign_name
  • contact_list_id
  • template_id
  • sms_type (sms or mms)
  • sms_body
  • numbers[]

Optional fields

  • file (required for MMS)
  • opt_out_link
  • batch_process
  • batch_size
  • batch_frequency
  • selected_date
  • selected_time
  • selected_users
  • number_pool
  • round_robin_campaign
cURL
curl -X POST "https://api.texttorrent.com/api/v1/campaigning/bulk" \
  -H "X-API-SID: SID...................................." \
  -H "X-API-PUBLIC-KEY: PK....................................." \
  -H "Accept: application/json" \
  -F "campaign_name=Spring Sale Announcement" \
  -F "contact_list_id=45" \
  -F "template_id=12" \
  -F "sms_type=sms" \
  -F "sms_body=Hi {first_name}, don't miss our Spring Sale! Get 20% off all items. Shop now!" \
  -F "numbers[]=+15551234567" \
  -F "opt_out_link=true"
Success response
{
  "code": 200,
  "success": true,
  "message": "Campaign created successfully",
  "data": {
    "campaign_id": 567,
    "total_credit": 1875,
    "total_contacts": 1250,
    "total_segments": 1
  },
  "errors": null
}
TextTorrent bulk SMS API documentation showing campaign or recipient request fields

Open the complete endpoint documentation · Explore bulk SMS software

Picture Messaging

Send Supported Media Through Documented MMS Fields

MMS is supported on inbox send with an optional chatFile attachment and on campaign create with sms_type=mms plus a required file. Confirm the sending number exposes capabilities.mms before relying on picture messaging.

  • Inbox send: include chatFile with POST /api/v1/inbox/chat.
  • Campaign send: set sms_type=mms and include file with POST /api/v1/campaigning/bulk.
  • Active numbers expose capabilities.mms through GET /api/v1/inbox/numbers/active.
  • Not every number supports MMS.
  • Media support may vary by provider and carrier.
  • Message delivery does not prove the media was viewed.
  • Sensitive files should not be sent through an unapproved workflow.

Exact media size and type limits should be confirmed in the current API documentation and provider capability for the number in use.

Explore the MMS messaging platform

Inbound Messaging

Connect Customer Replies to Your Application

Customer replies enter TextTorrent conversation workflows and can be retrieved through inbox APIs. Incoming replies may also appear in Claims before a team member accepts them into the main inbox.

  1. 01

    Customer replies to a business number.

  2. 02

    TextTorrent stores the inbound conversation activity.

  3. 03

    Your application retrieves conversations with GET /api/v1/inbox or chat details with GET /api/v1/inbox/{id}.

  4. 04

    Unclaimed replies can be reviewed with Claims endpoints such as GET /api/v1/claim/list and GET /api/v1/claim/counts.

  5. 05

    Accepted conversations continue in the inbox workflow where applicable.

  6. 06

    Opt-out keywords and blacklist tools remain part of the broader messaging system.

TextTorrent inbound SMS workflow showing customer replies in the messaging inbox

Shared SMS Inbox · Two-Way Text Messaging

Message Status

Track Message Processing with Verified Status Data

Campaign analytics and message logs expose documented send_status values. An initial success response means the request was accepted into the workflow—not that every later delivery outcome is already final.

pending

Message is being processed or sent.

sent

Message was sent; delivery confirmation may still be pending.

delivered

Message was delivered according to provider feedback.

failed

Message failed to send.

undelivered

Message was sent but not delivered.

  • Sent does not necessarily mean delivered.
  • Delivered does not mean read.
  • Failed or undelivered results may include provider details where available.
  • Status updates may arrive asynchronously and should be re-checked through analytics or inbox records.
  • Marketing UI labels such as Accepted are not published here as API send_status values.
TextTorrent SMS API response showing message status and delivery information

Review campaign analytics in the API docs · Explore SMS analytics

Event Notifications

Retrieve Messaging Updates with Documented API Patterns

Current TextTorrent API documentation describes REST retrieval for inbox activity, campaign analytics, Claims, and credit logs. Best-practice notes mention polling or webhooks for real-time updates, but only a polling example is published today.

A webhook sends an HTTP request to your application when a supported messaging event occurs. TextTorrent’s public API documentation currently emphasizes REST retrieval and a polling example rather than a published push-event catalog.

Verified approaches today

  • Poll GET /api/v1/inbox for conversation updates.
  • Read campaign message logs through campaign analytics detail endpoints.
  • Monitor unclaimed activity with GET /api/v1/claim/counts and GET /api/v1/claim/list.
  • Review credit usage with GET /api/v1/user/credit-logs for a selected date range.

Not published as live facts

  • A public push-webhook event catalog
  • Webhook signature verification details
  • A documented webhook retry schedule
  • Claim-acceptance webhooks

Reliable event processing

  • Store message, campaign, and chat identifiers returned by the API.
  • Make processing idempotent when re-reading the same records.
  • Expect status values to change over time.
  • Do not invent event names or payload shapes.
  • Reconcile application state with analytics and inbox endpoints.
  • Log failures without storing unnecessary personal data.
TextTorrent SMS API documentation covering messaging event retrieval patterns
Contact Data

Connect Messaging with Contact Records and Groups

Contact endpoints support listing contact groups, adding and updating contacts, importing contacts, managing folders, and working with blocked-list or opt-out-word tools documented in the API.

  • GET /api/v1/contact/list
  • POST /api/v1/contact/add
  • PUT /api/v1/contact/{id}
  • POST /api/v1/contact/import
  • Blocked-list and opt-out-word endpoints documented in /docs/api
  • Creating or importing a contact through an API does not establish consent to send messages.

Explore contact management · Explore SMS opt-out management

Sending Numbers

Use Registered and Properly Configured Business Numbers

API access does not bypass number and registration requirements. Use active numbers from GET /api/v1/inbox/numbers/active and confirm SMS or MMS capability before sending.

  • The sending number must exist in the account.
  • The number must support the requested capability.
  • Local application-to-person messaging generally requires A2P 10DLC registration.
  • Number status should be ready before sending.
  • MMS requires an MMS-capable number.
  • Opt-outs must still be respected.
  • API keys cannot send from arbitrary caller IDs or unowned numbers.

Local Numbers · A2P 10DLC Registration

Account Scope

Keep API Requests Inside the Correct Account or Sub-Account

TextTorrent supports parent and sub-account operations through act-as headers, Base64 email parameters, and inbox scope controls.

X-ACT-AS-USER

Parent accounts can act as an active sub-account by sending that user’s email in the X-ACT-AS-USER header.

email query parameter

Some list endpoints accept a Base64-encoded sub-user email so a parent can inspect that user’s resources.

scope=include-all-sub-users

GET /api/v1/inbox supports scope=include-all-sub-users so a parent account can retrieve conversations across sub-users in one request.

TextTorrent API documentation showing verified sub-account scope parameters

Rate limits apply per parent user, not separately per sub-account, according to current authentication documentation.

Explore SMS sub-accounts

API Errors

Handle Validation, Authentication, and Messaging Errors Clearly

TextTorrent API responses use a consistent envelope with code, success, message, data, and errors.

  • 200 / 201 success
  • 400 bad request
  • 401 unauthorized
  • 403 forbidden
  • 404 not found
  • 422 validation or business-rule failure
  • 429 rate limit exceeded
  • 500 / 503 server availability issues
Validation error
{
  "code": 422,
  "success": false,
  "message": "Validation Error",
  "data": null,
  "errors": {
    "message": ["The message field is required."]
  }
}
Insufficient credits
{
  "code": 422,
  "success": false,
  "message": "You do not have enough credits to perform this action.",
  "data": null,
  "errors": null
}
  • Do not retry permanent failures such as invalid numbers or unchanged validation errors.
  • Handle opt-out and blacklist conditions through the documented suppression tools.
  • Treat 429 as temporary and honor Retry-After.
  • Surface human-readable message fields to operators while logging structured errors for debugging.
TextTorrent SMS API documentation showing a structured validation error
Integration Limits

Build Around Verified API and Messaging Limits

The documented API rate limit is 60 requests per minute per API key. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

  • Respect HTTP rate-limit responses.
  • Use backoff for temporary 429 or availability errors.
  • Do not retry validation failures unchanged.
  • Do not retry messages blocked because of opt-out status.
  • Avoid duplicate sends by storing request identifiers.
  • Use application queues for large workflows.
  • Review campaign and number capacity.
  • Monitor credit balance with GET /api/v1/user/credit-logs.

Unlimited throughput and guaranteed synchronous processing are not claimed.

Secure Integration

Protect Credentials, Messages, and Customer Data

Treat messaging credentials and customer content as sensitive operational data.

  • Keep API keys server-side.
  • Use HTTPS.
  • Restrict access to logs.
  • Redact phone numbers and message bodies where possible.
  • Avoid storing sensitive content unnecessarily.
  • Rotate exposed credentials.
  • Limit production access.
  • Avoid placing API keys in URLs.
  • Move sensitive documents to approved secure channels.

Specific security certifications are not claimed on this page unless separately verified.

Common Integrations

Connect SMS to Existing Business Workflows

These examples show practical API use without implying native connectors for every CRM or operations platform.

CRM Lead Follow-Up

Who sends

Sales and RevOps teams

Why

Acknowledge opted-in leads from an application event and keep identifiers in the CRM.

  • Send acknowledgment after a verified lead event
  • Store message identifiers
  • Retrieve replies through inbox APIs
  • Create sales tasks in the CRM

Do not imply that every CRM is natively supported.

Explore CRM Lead Follow-Up messaging

Application and Document Reminders

Who sends

Operations teams

Why

Trigger reminders from an internal system while directing customers to approved channels.

  • Trigger a reminder from an internal system
  • Direct customers to an approved submission process
  • Retrieve replies
  • Update operational status

Avoid sensitive data in text messages.

Explore Application and Document Reminders messaging

Customer Support

Who sends

Support teams

Why

Send service updates and route conversation activity into team workflows.

  • Send service updates
  • Retrieve customer replies
  • Route conversations into the shared inbox
  • Store status in a support application

Use Claims and inbox ownership for team follow-up.

Explore Customer Support messaging

Status and Notification Workflows

Who sends

Product and operations teams

Why

Send permitted reminders and status notices through registered use cases.

  • Appointment reminders
  • Order or delivery updates
  • Property alerts
  • Policy or account notifications

Only send messages permitted by consent and registration.

Explore Status and Notification Workflows messaging
API Workflow Example

Send a Lead Acknowledgment and Process the Reply

Scenario: a business receives an opted-in lead through its application and needs a consistent first SMS plus a path for the reply.

Example message

Hi [First Name], this is [Company Name]. We received your request and will follow up shortly. Reply here if you have questions. Reply STOP to opt out.

  1. 01

    Application creates or retrieves the contact through contact endpoints.

  2. 02

    Application confirms current subscriber or blacklist status where available.

  3. 03

    Application starts or reuses a conversation, then sends SMS with POST /api/v1/inbox/chat.

  4. 04

    TextTorrent returns a message identifier such as id and msg_sid.

  5. 05

    Application stores the identifier.

  6. 06

    Later status is reviewed through campaign analytics or inbox records.

  7. 07

    Customer replies.

  8. 08

    Application retrieves the reply with inbox APIs.

  9. 09

    Reply may also appear in Claims or the shared inbox where applicable.

  10. 10

    A team member continues the conversation.

Example wording must be adapted to the business use case, consent process, and registration details. Creating a contact through the API does not create consent.

View API Documentation

Avoid These Mistakes

Common Problems in SMS API Implementations

Most integration failures come from credential exposure, incorrect assumptions about delivery, or undocumented event contracts.

Exposing API Keys in Frontend Code

Exposing API Keys in Frontend Code

Keys must remain server-side.

Retrying Permanent Errors

Retrying Permanent Errors

Do not retry opt-outs, invalid numbers, or unchanged validation failures.

Ignoring Asynchronous Statuses

Ignoring Asynchronous Statuses

An initial success response may not equal final delivery.

Treating Delivered as Read

Treating Delivered as Read

SMS delivery does not provide a read receipt.

Assuming Undocumented Webhooks

Assuming Undocumented Webhooks

Do not invent event names or payloads. Use documented retrieval endpoints until a webhook catalog is published.

Sending Before Number Registration Is Ready

Sending Before Number Registration Is Ready

Confirm number and campaign status first.

Ignoring Subscriber Status

Ignoring Subscriber Status

Check opt-outs and blacklist records.

Logging Sensitive Data

Logging Sensitive Data

Protect phone numbers, message bodies, credentials, and customer information.

Responsible Operations

API Access Does Not Replace Consent or Registration

Developer integrations must still follow the same messaging responsibilities as the rest of the TextTorrent platform.

  • Confirm consent before promotional or outreach messaging.
  • Keep message content aligned with the registered use case.
  • Respect opt-out and blacklist status.
  • Use active, capability-ready numbers.
  • Protect credentials and customer data.
  • Review credits, rate limits, and error handling before large sends.
  • Provide a path to human support when replies need judgment.

TextTorrent provides messaging APIs and operational tools, not legal advice. Customers and developers remain responsible for consent, registration accuracy, message content, opt-out handling, data protection, and compliance with applicable laws, carrier requirements, industry rules, and the terms of their messaging registration.

Why TextTorrent

Connect API Messaging with the Full TextTorrent Workflow

TextTorrent keeps developer endpoints connected to inbox conversations, campaigns, contacts, analytics, and account structure—not as an isolated send-only gateway.

Messaging and Operational APIs

Messaging and Operational APIs

Connect supported messages, contacts, campaigns, Claims, and reporting operations.

Inbound Replies and Status Records

Inbound Replies and Status Records

Retrieve customer-reply and message-status data through documented endpoints.

Shared Inbox Connection

Shared Inbox Connection

Move API-generated conversations into team workflows where supported.

Account and Sub-Account Context

Account and Sub-Account Context

Keep resources connected to parent and sub-account structures with act-as and scope controls.

Analytics and Message Logs

Analytics and Message Logs

Review messaging activity in the TextTorrent interface and through supported analytics APIs.

Frequently Asked Questions

SMS API and Webhook Questions, Answered

Practical answers for developers evaluating TextTorrent as a business messaging API.

An SMS API lets software applications send and manage supported text-messaging operations programmatically. With TextTorrent, that includes authenticated REST requests for inbox messaging, campaigns, contacts, Claims, analytics, credits, and related account operations documented at /docs/api.

Include both X-API-SID and X-API-PUBLIC-KEY headers on every request. Optional X-ACT-AS-USER lets a parent account act as an active sub-account by email. Unauthenticated requests receive 401 Unauthorized.

Yes. POST /api/v1/campaigning/bulk creates SMS or MMS campaigns using a contact list, template, message body, and sending numbers. Scheduling and batch options are documented for that endpoint. Bulk campaign creation is unavailable during trial according to current documentation.

Yes. Inbox send supports an optional chatFile media attachment, and campaign create supports sms_type=mms with a required file. Confirm the number exposes MMS capability before relying on picture messaging.

Current public documentation focuses on retrieving inbound conversation activity through inbox APIs and a polling example. A dedicated push-webhook event catalog, signing method, and retry schedule are not currently documented, so do not invent webhook contracts.

Documented campaign message send_status values include pending, sent, delivered, failed, and undelivered. Sent does not necessarily mean delivered, and delivered does not mean read.

The documented limit is 60 requests per minute per API key. Exceeding it returns 429 Too Many Requests with a Retry-After header. Rate limits apply per parent user, not separately per sub-account.

Yes. Use X-ACT-AS-USER for act-as requests, Base64 email parameters on supported list endpoints, and scope=include-all-sub-users on GET /api/v1/inbox for parent-account inbox aggregation.

TextTorrent provides blocked-list, Claims blacklist, and opt-out-word tooling documented in the API and product. Developers and customers remain responsible for checking suppression status and not continuing promotional messaging after STOP.

No. API access lets an application submit messages through the supported workflow, but delivery can still be affected by consent, contact quality, registration, number configuration, content, provider responses, carrier filtering, and other factors.