Introduction

This guide provides the information required to integrate with the Delivyr SMPP interface for sending and receiving SMS messages.

The Short Message Peer-to-Peer (SMPP) protocol is an industry-standard protocol used by telecommunications providers and messaging platforms to exchange SMS messages between applications and Short Message Service Centers (SMSCs).

Delivyr supports SMPP Version 3.4, providing a reliable, high-performance interface for:

• Sending outbound SMS messages
• Receiving inbound SMS messages (if enabled)
• Receiving delivery receipts (DLRs)
• Scheduling message delivery
• High-throughput messaging applications

Note: SMPP Version 3.4 is supported. Earlier versions, such as SMPP 3.3, are not supported.

Connection Parameters

Binding

Clients may bind using any of the following modes:

• bind_transmitter
• bind_receiver
• bind_transceiver

To receive delivery reports (DLRs), your application must bind as either:

• bind_receiver, or
• bind_transceiver

Delivery reports are only available if they have been enabled for your account.

By default, multiple simultaneous SMPP sessions may be supported. Contact Delivyr if additional concurrent sessions are required.

Supported SMPP PDUs

The following SMPP operations are supported:

• bind_transmitter
• bind_receiver
• bind_transceiver
• unbind
• submit_sm
• deliver_sm
• enquire_link

Delivery Reports

When a message is accepted by the Delivyr platform, delivery reports (DLRs) can be returned to your SMPP client to indicate the final delivery status.

Delivery reports are sent using the deliver_sm PDU.

Delivery Report Format

Delivery reports use the following standard SMPP format:

id:<message_id> sub:<submitted_count> dlvrd:<delivered_count>
submit date:<submit_date> done date:<completion_date>
stat:<status> err:<error_code>

Example

id:1234567890
sub:001
dlvrd:001
submit date:2507081430
done date:2507081431
stat:DELIVRD
err:000

Delivery Status Values

The stat field indicates the current or final delivery state of the message.

Data Coding Scheme (DCS)

The Data Coding Scheme (DCS) determines how the message body is encoded.

Notes

• Use DCS 0 for standard GSM 7-bit text.
• Use DCS 8 when sending Unicode characters such as emojis or non-Latin languages.
• Use DCS 3 when Latin-1 encoding is specifically required.
• Message encoding must match the character set used in the message payload.

Character Encoding Recommendations

Choose the appropriate encoding based on your message content:

SMPP Command Responses

Every submit_sm request sent to the Delivyr SMPP platform receives a corresponding submit_sm_resp response.

The response indicates whether the message was successfully accepted for processing or if an error occurred.

A successful submit_sm_resp confirms that the platform has accepted the message. It does not guarantee final delivery to the recipient. Final delivery status is provided separately through a Delivery Report (DLR) using the deliver_sm PDU.

The Delivyr SMPP interface is fully compliant with the SMPP Version 3.4 specification.

Scheduled Delivery

Delivyr supports scheduled message delivery using the standard SMPP relative time format.

The schedule_delivery_time field may be populated when submitting a message to request delayed delivery.

Relative Time Format

The SMPP relative time format is:

YYMMDDhhmmsstnR

Where:

Example

070605040302100R

This schedules the message for delivery:

• 7 years
• 6 months
• 5 days
• 4 hours
• 3 minutes
• 2 seconds
• 1 tenth of a second

after the request is submitted.

Note: Scheduled delivery is subject to carrier support and message validity settings.

Delivery Workflow

The typical message flow is:

Client
   │
   │ submit_sm
   ▼
Delivyr SMPP Platform
   │
   │ submit_sm_resp
   ▼
Message Accepted
   │
   │
Carrier Network
   │
   ▼
Recipient Device
   │
   │
deliver_sm (Delivery Report)
   ▼
Client

Keep-Alive Connections

To maintain an active SMPP session, clients should periodically send the enquire_link PDU.

Delivyr responds with an enquire_link_resp to confirm that the connection remains healthy.

It is recommended to:

• Send an enquire_link every 30 seconds during idle periods.
• Reconnect if a response is not received within the configured timeout.
• Implement automatic reconnection logic for production environments.

Optional SMPP Features

In addition to standard SMS messaging, Delivyr may provide optional SMPP services that can be enabled on your account.

These services require account provisioning and, in some cases, the use of specific system_type values during the SMPP bind process.

Note: Contact Delivyr Support to determine which optional services are available for your account.

Number Lookup (Optional)

The Number Lookup service allows your application to retrieve information about a destination mobile number before sending a message.

Typical use cases include:

• Mobile number validation
• Network identification
• Mobile Number Portability (MNP)
• Routing optimization
• Roaming detection

When enabled, the Number Lookup service uses your existing SMPP credentials.

During the bind process, configure:

system_type = HLR

Requesting a Number Lookup

A lookup request is submitted using the standard submit_sm PDU.

Only the destination address (destination_addr) is required.

All other message parameters are ignored for lookup requests.

After the request is accepted, Delivyr returns a standard submit_sm_resp containing a message identifier.

When processing is complete, the lookup result is delivered using a deliver_sm PDU.

Lookup Response

A successful lookup may include information such as:

• IMSI (International Mobile Subscriber Identity)
• Serving MSC
• Home Network
• Roaming Network
• Country
• Country Code
• Network Prefix
• MCC/MNC
• Mobile Number Portability status

Depending on your service package, additional optional fields may also be returned.

Optional TLV Parameters

Lookup results may also include optional SMPP TLV (Tag-Length-Value) parameters.

Examples include:

The exact TLVs returned depend on the services enabled for your account.

Response Workflow

submit_sm
      │
      ▼
submit_sm_resp
      │
      ▼
Lookup Processing
      │
      ▼
deliver_sm
      │
      ▼
Lookup Information Returned

Flash SMS (Class 0)

Delivyr supports Flash SMS (Class 0) messaging over SMPP.

Unlike standard SMS messages, Flash SMS messages are displayed immediately on the recipient's device without being stored in the device's inbox (subject to handset and carrier support).

Flash SMS is commonly used for:

• One-time passwords (OTP)
• Emergency notifications
• Security alerts
• Critical account notifications
• Time-sensitive operational messages

Note: Support for Flash SMS varies by carrier and mobile device. Delivery behavior may differ depending on the recipient's network.

Enabling Flash SMS

Flash SMS is an optional feature that must be enabled on your Delivyr account.

If your account has multiple messaging profiles or service types, Delivyr will provide the appropriate configuration during onboarding.

Sending a Flash SMS

Flash SMS messages are submitted using the standard submit_sm PDU.

The message body and addressing fields are identical to those used for a standard SMS.

The primary difference is that the message must be submitted with the appropriate Data Coding Scheme (DCS) or messaging class that identifies the message as Class 0.

Example

submit_sm
    source_addr        = MyApp
    destination_addr   = 15551234567
    short_message      = Your verification code is 482913
    data_coding        = Class 0 (Flash SMS)

Delivery Reports

Flash SMS messages generate delivery reports in the same manner as standard SMS messages.

Delivery receipts are returned using the deliver_sm PDU when delivery reporting is enabled.

The same delivery status values apply:

• DELIVRD
• EXPIRED
• UNDELIV
• ACCEPTD
• UNKNOWN
• ENROUTE
• REJECTD

Limitations

When using Flash SMS, keep the following considerations in mind:

• Long (concatenated) Flash SMS messages may not be supported by all carriers or devices.
• Flash SMS behavior is ultimately determined by the recipient's handset and mobile network.
• Some devices may automatically save Flash SMS messages after they are displayed.
• Unicode support depends on carrier and handset capabilities.

Best Practices

• Use Flash SMS only when immediate user attention is required.
• Keep messages concise whenever possible.
• Avoid sending promotional or marketing content as Flash SMS.
• Test delivery across multiple carriers and devices before deploying to production.

SMPP Command Status Codes

Every submit_sm request receives a corresponding submit_sm_resp response containing a command status.

A command status indicates whether the SMPP server successfully accepted the request for processing or if an error occurred.

Note: A successful command status confirms that the request has been accepted by the Delivyr platform. It does not guarantee successful delivery to the recipient. Final delivery status is communicated separately through Delivery Reports (DLRs).

Common Command Status Codes

The following command status codes are commonly returned by the Delivyr SMPP platform.

Additional SMPP command status codes defined by the SMPP 3.4 specification may also be returned where applicable.

Handling Command Status Responses

Applications should always inspect the command status before assuming that a message has been accepted.

General recommendations:

• Retry temporary failures using exponential backoff.
• Do not retry permanent failures without correcting the request.
• Log all non-zero command status values for troubleshooting.
• Monitor recurring failures to identify routing or account issues.

Common Failure Categories

Best Practices

To improve delivery success rates:

• Validate destination phone numbers before submission.
• Use valid sender IDs or originating addresses.
• Avoid duplicate message submissions.
• Monitor delivery reports in addition to command status responses.
• Implement retry logic only for recoverable errors.

GSM Delivery Error Codes

When a message cannot be delivered, the Delivery Report (DLR) may include a GSM error code identifying the reason for the failure.

These error codes are returned in the err field of the delivery report and can be used to determine whether a message should be retried or considered permanently undeliverable.

Error Code Reference

Permanent vs. Temporary Errors

Understanding whether an error is permanent or temporary is important when implementing retry logic.

Permanent Errors

Permanent errors indicate that the message is unlikely to succeed if retried without changing the request.

Examples include:

• Unknown subscriber
• Illegal subscriber
• Unsupported service
• Invalid destination
• Illegal equipment

For these errors:

• Do not automatically retry.
• Log the failure.
• Review the destination number or account configuration.

Temporary Errors

Temporary errors indicate that delivery may succeed at a later time.

Examples include:

• Subscriber temporarily unavailable
• Network congestion
• System failure
• Recipient device unavailable

For these errors:

• Retry using exponential backoff.
• Limit the total number of retry attempts.
• Monitor for recurring failures.

Sample Delivery Report

id:847392001
sub:001
dlvrd:000
submit date:2607081015
done date:2607081017
stat:UNDELIV
err:027

In this example:

• Delivery Status: UNDELIV
• GSM Error Code: 27
• Meaning: Recipient temporarily unavailable (Absent Subscriber)
• Recommended Action: Retry later.

GSM Delivery Error Codes (Continued)

The following GSM error codes may be returned in Delivery Reports (DLRs). These codes provide additional information about network, routing, and service-level failures.

Error Code Reference

Recommended Error Handling

Different categories of failures should be handled appropriately by your application.

Retry Strategy

When implementing retries, consider the following best practices:

• Retry only temporary failures.
• Limit the maximum number of retry attempts.
• Increase the delay between retries using exponential backoff.
• Avoid retrying immediately to prevent unnecessary load.
• Log all permanent failures for operational review.

Logging Recommendations

For troubleshooting and support, record the following information for each failed message:

• Message ID
• Destination address
• Submission timestamp
• Delivery status
• GSM error code
• SMPP command status
• Retry attempt count (if applicable)

Maintaining detailed logs can significantly reduce troubleshooting time and improve visibility into delivery performance.

GSM Delivery Error Codes (Continued)

The following error codes represent additional network, signaling, and protocol-level failures that may be returned in Delivery Reports (DLRs).

Applications should use these values to determine whether a retry is appropriate or whether the message should be considered permanently undeliverable.

Error Code Reference

Network-Level Failures

These errors generally originate within the carrier or signaling network rather than the Delivyr platform.

Typical causes include:

• Carrier maintenance
• SS7 signaling failures
• Routing interruptions
• Network congestion
• Temporary infrastructure outages

In most cases, these errors are temporary and may succeed if retried after a delay.

Recommended Retry Strategy

When retrying failed messages:

• Retry only temporary network failures.
• Use exponential backoff.
• Respect message validity periods.
• Avoid excessive retry attempts.
• Monitor recurring failures to identify routing issues.

Additional Delivery Error Codes

The following error codes represent additional provider and network conditions that may be encountered during message delivery.

Error Code Reference