How to send sms from C#.Net

To send sms from C#.Net you have several options. You can use the C# SMS API library of Ozeki, or you can use HTTP requests. To send a text message in C#.Net the best option depends on the C# project type you use. If you write code to serve web requests, such as C# on an ASP webpage, you should go for the HTTP requests. If you create a desktop application, a windows service or a mobile application for Android or iPhone, it is best to use the C# SMS API library. This guide (Figure 1) is concentrating on SMS sending only. If you need to do both sending and receiving, you may start by reading The best C# SMS API in 2024 guide first.

How to send SMS from C#.Net
Figure 1 - How to send SMS from C#.Net

Download the C# sms api library (free source code)

A fully working example of the C# sms api can be downloaded from the following URL. This code is provided free of charge, and can be freely modified and redistributed by you.

Download: OzekiConsole.zip (51 Kb)

How do I send sms from a C# desktop app

To send a text message from a desktop app (or a console app or Windows service) has different requirements to sending an sms from a website. A desktop app runs for a signification amount of time (many minutes, days or even weeks). In this case it is beneficial to maintain a permanent connection to the SMS gateway. Using one time fire and forget web requests is not a good choice for these apps. The biggest benefit of maintaining a permanent connection is that you get information about message delivery events, such as submission reports, delivery reports and sms delivery failures.

To send sms from a C# desktop app use the provided example first (as you can see on Figure 2):

  1. Connect to ozeki sms gateway using the ozx username and password you have created in the sms gateway user interface. To connect use the "connect hostname:port username password" command.
  2. Send your text message. This can be dony by typing "send phonenumber message text" if you use the example console application for sending.
  3. Wait for sms submit reports and sms delivery reports. You might notice that these reports are printed on the screen, and they contain the same message ID that was returned when you have sent the sms.

Example console application written in C#.Net. The source code of this console application is available on the C# SMS API with source code page.

csharp sms api examples
Figure 2 - How to send an SMS from C# sms api

The above example shows you the required steps. You can see that first a permanent connection is established to the SMS gateway, and after this, the message is sent. Finally, you see the message accept report and the messages submit report.

To send sms from C#, use the following source code:

  • Client = new OzxClient();
  • Client.AutoReconnect = true;
  • Client.Connect("127.0.0.1", 9518, "testuser", "testpassword");
  • Client.Connect("127.0.0.1", 9518, "testuser", "testpassword");
  • Client.Send(new OzxMessage() {ToAddress="+36111111",Text="This is the text to send text from C#"});

When you set the Client.Autoconnect property to true, it makes sure, that the client will reconnect to the SMS gateway even if the network connection is lost temporarily or the sms gateway is restarted.

To receive sms delivery reports in C#, you need to sign up for the events:

  • Client.OnMessageAcceptedForDelivery += Client_OnMessageAcceptedForDelivery;
  • Client.OnMessageNotAcceptedForDelivery += Client_OnMessageNotAcceptedForDelivery;
  • Client.OnMessageSubmitSuccess += Client_OnMessageSubmitSuccess;
  • Client.OnMessageSubmitFailed += Client_OnMessageSubmitFailed;
  • Client.OnMessageDeliverySuccess += Client_OnMessageDeliverySuccess;
  • Client.OnMessageDeliveryFailed += Client_OnMessageDeliveryFailed;

These events will be fired when the SMS gateway sends the appropriate reports over the permanent connection we have created using connect. This is the biggest benefit of using a permanent connection. You get instant notifications about these sms delivery related events. Such notifications are hard to get if you use an HTTP SMS api. On the other hand, this information is crucial for any business, and you must process them to build a good SMS software.

What kind of SMS delivery reports are provided by the C# sms api?

The C# SMS api returns five kind of SMS delivery reports. These are presented as C# events. They are SMS accept event, SMS not accepted event, SMS submit success event, sms submit failed event, sms delivery success event, sms delivery failed event.

SMS accept event: The SMS accepted event is raised when the Ozeki SMS gateway accepts the SMS for delivery and puts into the outbox of the user account.

SMS not accepted event: The SMS not accepted event is raised if the Ozeki SMS gateway does not accept the SMS for delivery. This can happen for example if the user runs out of SMS credits, or the disk is full or some other error happens in the sms gateway.

SMS submit successful event: The SMS submit successful event is triggered when the SMS is delivered to the mobile network successfully. The mobile network returns an SMS submit report, and this report is forwarded to the C# SMS API client through the established connection. The SMS submit successful event is raised for example when the SMS is submitted by the SMPP client that connects the system to the mobile network over the Internet. If you send SMS messages through an android sms gateway, this event happens when the sms is submitted by the sms modem built into the android phone. If you send SMS through a standard sms modem or a gsm modem pool that is connected to your server with a data cable, the event is fired when the modem returns the 1 byte submit successful reference code to the AT+CMGS modem command.

sms submit failed event: The SMS submit failed event happens if the SMS could not be submitted for any reason to the mobile network by the Ozeki SMS Gateway. For example if the Internet link used by the SMPP client mobile network connection is offline or if the SMPP Server returns an SMPP error message when the SMS is sent. If you send your SMS messages through the android sms gateway, and the android mobile phone's plan runs out of credits, or the phone is not registered to the mobile network you also receive this event. It might also be possible, that the SMS routing table is not configured properly. SMS submit error can also happen if you use a gsm modem for sms delivery and the data cable between the modem and the pc is disconnected or broken. In all of these cases you will have an error message in the Event Args attached to this event to give you an idea what could be the reason for SMS submission failure.

sms delivery success event: The sms delivery success event is called when the SMS is successfully delivered to the recipient handset. In this case an SMS delivery report is returned by the mobile network to the SMS gateway. The SMS delivery report contains the timestamp of the delivery and the successful status code of the delivery. The SMS gateway forwards this information to the C# SMS API. When you receive an SMS delivery report event in C#, you can be sure, that your SMS was received by the recipient.

sms delivery failed event: The sms delivery report in C# can be handled with the sms delivery failed event if the delivery report contains an unsuccessful delivery status code. This can happen for example if the mobile phone where the SMS was sent to is never switched on. This event happens rarely, because most mobile network do not return negative delivery reports.

Send sms from C# SMS API (free to use source code)

To send SMS from C# use the following source code. This source code can be freely modified and redistributed. Note that you can also freely modify and redistribute the source of the C# SMS API library in the Ozeki.Libs.Ozx project. 

using System;
using OZX;

namespace OzekiConsoleClient
{
    class Program
    {
        static OzxClient Client;

        static void Main(string[] args)
        {
         	Client = new OzxClient();
            Client.AutoReconnect = true;

            Client.OnMessageAcceptedForDelivery += Client_OnMessageAcceptedForDelivery;
            Client.OnMessageNotAcceptedForDelivery += Client_OnMessageNotAcceptedForDelivery;
            Client.OnMessageSubmitSuccess += Client_OnMessageSubmitSuccess;
            Client.OnMessageSubmitFailed += Client_OnMessageSubmitFailed;
            Client.OnMessageDeliverySuccess += Client_OnMessageDeliverySuccess;
            Client.OnMessageDeliveryFailed += Client_OnMessageDeliveryFailed;
            Client.OnMessageViewed += Client_OnMessageViewed;
            Client.OnConnected += Client_OnConnected;
            Client.OnDisconnected += Client_OnDisconnected;
        
            Client.Connect("127.0.0.1",9580,"testuser","testpass");
        }

        static void Client_OnConnected(object sender, EventArgs e)
        {
            Console.WriteLine("Successfully connected.");
            
            var msg = new OzxMessage();
            msg.ToAddress = recipient;
            msg.Text = message;

            Console.WriteLine("Sending message. ID: "+msg.ID);
            Client.Send(msg);
        }

        static void Client_OnDisconnected(object sender, OzxArgs< string > e)
        {
            Console.WriteLine("Connection closed. Reason: " + e.Item.ToString());
        }

        static void Client_OnMessageAcceptedForDelivery(object sender, OzxArgs< string > e)
        {
            Console.WriteLine("Message accepted for delivery. ID: " + e.Item.ToString());
        }

        static void Client_OnMessageNotAcceptedForDelivery(object sender, OzxArgs< string, string > e)
        {
            Console.WriteLine("Message rejected. ID: " + e.Item1.ToString()+" Reason: "+e.Item2);
        }

        static void Client_OnMessageSubmitSuccess(object sender, OzxArgs< string, DateTime > e)
        {
            Console.WriteLine("Message submitted. ID: "+e.Item1+" Date: "+e.Item2);
        }

        static void Client_OnMessageSubmitFailed(object sender, OzxArgs< string, DateTime, string > e)
        {
            Console.WriteLine("Message submit failed. ID: " + e.Item1 + " Date: " + e.Item2+" Reason: "+e.Item3);
        }

        static void Client_OnMessageDeliverySuccess(object sender, OzxArgs< string, DateTime > e)
        {
            Console.WriteLine("Message delivered. ID: " + e.Item1 + " Date: " + e.Item2);
        }

        static void Client_OnMessageDeliveryFailed(object sender, OzxArgs< string, DateTime, string > e)
        {
            Console.WriteLine("Message delivery failed. ID: " + e.Item1 + " Date: " + e.Item2 + " Reason: " + e.Item3);
        }

        static void Client_OnMessageViewed(object sender, OzxArgs< string, DateTime > e)
        {
            Console.WriteLine("Message viewed. ID: " + e.Item1 + " Date: " + e.Item2);
        }
    }
}

How to test sms sending with an C#

To test sms sending in the C# sms api you have two options: You can use the built in sms tester connection or you can setup two sms gateways to have a more realistic testing environment. If you setup two sms gateways, first you need to configure the first SMS gateway as an SMPP simulator. This SMS gateway will provide SMPP server service to the second SMS gateway. It will operate the same way the SMSC of a mobile network operator would operate. The second SMS gateway will connect to the first using an SMPP client connection, and it will provide C# SMS API service to your C# sms application.

FAQs

The delivery report (onMessageDeliveryFailed) is retrieved for every failed attempt or is just retrieved when the max number of tries is reached?

The message remains in a pending state until the maximum number of delivery attempts is exhausted.

Is it possible to store the incoming SMS delivery reports into SQL?

To receive delivery reports for your SMS messages, navigate to the "Edit" menu and select "Server preferences." Within the "Advanced" tab, locate the checkbox labelled "Copy delivery reports for users" and ensure it's checked. If you have configured an SQL to SMS gateway, incoming delivery reports will be automatically stored within the database as standard incoming messages. Here's how delivery status updates are reflected:

  • ozekimessageout Table and Status Updates: Provided you send messages from the "ozekimessageout" table, the "status" field automatically tracks the delivery state of each message. This field dynamically updates to reflect the following outcomes:
  • deliveredtonetwork: Message successfully submitted to the network.
  • deliveredtohandset: Message delivered to the recipient's phone.
  • deliveryerror: An error occurred during delivery.
This functionality provides a convenient way to monitor delivery status within the database itself.

More information