123eworld Knowledge Hub → Transactional SMS → Page 179
Transactional SMS API Request Validation: Phone Numbers, Sender IDs, Templates, Variables and Payload Limits
How to validate transactional SMS API requests safely and consistently, from phone numbers and sender IDs to templates, variables, payload size and business rules.
Validation layers
Validate requests in layers: transport syntax, authentication, schema, tenant policy, business rules and provider eligibility. Early validation reduces wasted queue and provider capacity.
Phone numbers
Normalize phone numbers to a documented canonical representation and validate country and destination policy. Do not rely on string length alone because international numbering plans vary.
Sender IDs
Validate sender identifiers against the tenant's approved configuration and destination rules. A syntactically valid sender is not necessarily an authorized sender.
Templates
If template-based messaging is used, verify that the template exists, is active and belongs to the tenant. Store the selected revision with the logical message.
Variables
Validate required variables, types, lengths and allowed characters after applying the template schema. The final rendered content should then be checked for encoding and segment count.
Payload limits
Set limits on body size, number of recipients, variable length and metadata. Limits protect both API infrastructure and downstream providers.
Business rules
A valid payload may still violate suppression, quota, sender, destination or compliance policy. Apply these rules before queue admission.
Normalization
Normalization should be deterministic. The same input should produce the same canonical destination or sender representation so idempotency and billing remain consistent.
Error reporting
Return actionable field-level errors while avoiding disclosure of internal policy details that could help abuse.
Testing
Test malformed numbers, unsupported destinations, inactive templates, missing variables, oversized values, forbidden senders and quota violations.
Operational checklist
Define normalization, schema validation, business rules, payload limits, error codes and the exact point at which a request becomes accepted.
Developer takeaway
Validation is not one regex. It is a layered admission system that protects correctness, security and downstream capacity.
Canonicalization
Phone-number canonicalization should happen before idempotency and duplicate checks if the business identity of the destination depends on normalized form. For example, two textual representations of the same international number should not accidentally become two separate destinations.
Sender validation
Sender rules may differ by destination and message type. The validation layer should therefore check tenant authorization first and route eligibility second. This prevents a customer from using a syntactically valid sender that is not approved for its account.
Variable rendering
Render variables only after validating their schema. Then perform final length and encoding checks on the rendered message. This ordering prevents a template that looks valid during configuration from producing an oversized or Unicode-heavy production message.
Limits and abuse
Payload limits also protect against accidental abuse. A request containing thousands of recipients or an enormous variable can consume memory before the platform reaches its rate-limit layer. Validate size and structure early, before expensive operations.
Validation order
Authentication should precede tenant-specific validation, while inexpensive syntax checks should precede database lookups. This creates a predictable cost profile and reduces unnecessary work for malformed requests.
Validation evidence
Store useful rejection reason codes without retaining more sensitive input than necessary. Customers need enough information to fix the request, while the platform should avoid turning validation logs into a copy of all message content.
Final reference
Validation is successful when an accepted message is structurally correct, authorized, policy-compliant and safe for downstream processing.
Country policy
Destination validation may depend on enabled countries, traffic type and customer permissions. Keep these policies configurable rather than embedding country rules throughout application code.
Template ownership
A template ID should always resolve within tenant scope. If templates are shared across tenants, that sharing should be an explicit controlled feature rather than an accidental consequence of a global database lookup.
Content limits
Limit not only raw request size but also rendered message size. A small template can produce a huge message after variable substitution, and that is the value that ultimately consumes processing capacity.
Preflight validation
For high-volume customers, provide a validation or preview endpoint that can detect errors before production submission. This reduces failed sends and improves developer confidence.
Consistency
Use the same validation libraries in API, SDK helper and sandbox where possible. Differences between environments create false confidence and difficult production debugging.
Final safeguard
Validation should make an accepted request boring: authorized, normalized, policy-compliant and ready for deterministic downstream processing.
Advanced production guidance
Validation should be designed with a clear acceptance boundary. Before acceptance, the platform may reject a request because of syntax, authorization, policy or quota. After acceptance, failures should be represented through the message lifecycle rather than returning a misleading synchronous validation error. This distinction is important for customer applications because they need to know whether to correct the original request or monitor an already accepted message. Document exactly when a request becomes an accepted logical message.
Reference architecture note
A strong validation layer also improves security by reducing unexpected downstream inputs. Provider adapters should receive normalized values rather than arbitrary customer payloads. This reduces the number of edge cases each adapter must handle and makes provider routing more deterministic. Validation should be shared where possible so every route receives the same canonical destination, sender and message representation.
Implementation detail
Validation rules should be reviewed whenever provider capabilities change. A new destination route may allow a sender type that was previously invalid, while a regulatory or carrier change may make a previously accepted combination unavailable. Keep policy configuration separate from low-level parsing so these changes can be updated without rewriting the entire API validation layer.
Operational reference
Validation performance should also be monitored. If a validation rule suddenly causes database latency to rise, the platform may be performing expensive lookups for every request. Keep inexpensive checks early and cache only safe configuration data. The objective is to reject bad requests quickly without making valid traffic slower.
Final engineering guidance
Request validation should also protect against unexpected Unicode, control characters and malformed structured input. The platform should normalize safely and reject values that cannot be represented by the provider or business policy. This is particularly important for sender identifiers and template variables, where hidden characters can create confusing delivery or display problems.
Knowledge-base guidance
Validation rules should have ownership and change history. If a carrier requirement changes, the platform should be able to identify when the rule changed and which requests were affected. This is particularly useful when customers compare yesterday's successful request with today's rejection. A versioned policy system makes such differences explainable.
Production reference
Validation should be applied consistently to synchronous API requests, batch items, scheduled messages and SDK helpers. If a batch endpoint accepts a value that the single-message endpoint rejects, customers will experience unpredictable behaviour. A shared validation model with endpoint-specific limits provides consistency while still allowing each operation to impose appropriate constraints.
Closing engineering guidance
The final validation decision should be persisted with useful normalized attributes. This allows support to understand why a request was accepted or rejected without reconstructing every rule from current configuration. If policy changes later, historical decisions remain explainable because the platform retains the relevant message and configuration evidence.
Final knowledge-base note
Validation should also be visible in the sandbox so developers can test rejection behaviour before production. The same sample payload should produce the same normalized outcome in sandbox and production unless a documented environment difference applies. This consistency is one of the strongest ways to turn validation rules into a dependable developer contract.
Final production rule
A validation rule should never depend on a provider response when the decision can be made from trusted local configuration. This keeps rejection latency predictable and avoids turning simple input errors into provider traffic.
Production readiness test
For production readiness, validation rules should have automated tests for normal inputs, boundary values, malformed inputs and policy changes. These tests should run before deployment and should include the final rendered message, not merely the raw request. When a validation change is intentional, the affected error code, documentation and customer migration guidance should be updated together. This keeps the validation layer predictable as the messaging platform grows.
Continue through the 123eworld Knowledge Hub
Explore the complete 123eworld Knowledge Hub for practical SMS API, transactional messaging and developer architecture guides.
Visit 123eworld.com for messaging and digital communication services.