Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Send SMS and MMS Messages in C# and .NET


In this tutorial, we'll show you how to use Twilio's Programmable Messaging to send SMS and MMS messages from your .NET Framework or .NET Core application.

(warning)

Warning

The code samples in this tutorial use Twilio's .NET helper library(link takes you to an external page). Let's get started!


Sign up for (or log in to) your Twilio account

sign-up-for-or-log-in-to-your-twilio-account page anchor
(information)

Info

If you have a Twilio account and Twilio phone number with SMS capabilities, you're all set! Feel free to jump straight to the code.

Before you can send messages, you'll need to sign up for a Twilio account(link takes you to an external page) and purchase a Twilio phone number(link takes you to an external page).

If you're brand new to Twilio, you can sign up for a free trial account(link takes you to an external page) to get started. Once you've signed up, head over to your Console(link takes you to an external page) and grab your Account SID and your Auth Token. You will need those values for the code samples below.

(warning)

Warning

If you are sending SMS to the U.S. or Canada, before proceeding further please be aware of updated restrictions on the use of Toll-Free numbers for messaging, including TF numbers obtained through Free Trial. Please click here(link takes you to an external page) for details.


Get a phone number with SMS (and MMS) capabilities

get-a-phone-number-with-sms-and-mms-capabilities page anchor

Sending messages requires a Twilio phone number with SMS capabilities. If you don't currently own a Twilio phone number with SMS capabilities, you'll need to buy one. After navigating to the Buy a Number page(link takes you to an external page), check the 'SMS' box and click 'Search':

Buy A Number.

If you live in the US or Canada and also wish to send MMS messages, you can select the 'MMS' box. When viewing the search results, you can see the capability icons in the list of available numbers:

Click Buy Button to Purchase an SMS-capable Number.

Find a number you like and click "Buy" to add it to your account.

(warning)

Warning

If you're using a trial account, you will need to verify your personal phone number via the console(link takes you to an external page) so that you can test sending SMSes to yourself.

Learn more about how to work with your free trial account.

Now that you have a Twilio phone number you can start sending messages to mobile devices.


Send an SMS message in C# and .NET via the REST API

send-an-sms-message-in-c-and-net-via-the-rest-api page anchor

To send an outgoing SMS message from your Twilio account you'll need to make an HTTP POST to Twilio's Message resource.

Twilio's NuGet package for .NET helps you to create a new instance of the Message resource, specifying the To, From, and Body parameters of your message. Let's create a new .NET project and add the Twilio NuGet Package.

Jump to the appropriate section below based on whether you are working with Visual Studio or the dotnet command line tool.

Create a new project with Visual Studio

create-a-new-project-with-visual-studio page anchor

Open Visual Studio and select the "File" menu and choose "New" then "Project..." and select "Console App (.NET Framework)" or "Console App (.NET Core)".

Visual Studio - New .NET Framework Project.

Then, select "Tools," "NuGet Package Manager," and "Package Manager Console" from the main menu in Visual Studio and type this command:


_10
Install-Package Twilio

You're now ready to skip to writing the code.

Create a new project with the .NET CLI

create-a-new-project-with-the-net-cli page anchor

Run these commands to create a new .NET project and install the Twilio NuGet package:


_10
mkdir TwilioSend
_10
cd TwilioSend
_10
dotnet new console
_10
dotnet add package Twilio

Write C# code to send an SMS

write-c-code-to-send-an-sms page anchor

Now, open the Program.cs file and replace it with the following code.

Send an SMS using the Programmable Messaging API

send-an-sms-using-the-programmable-messaging-api page anchor
C#

_27
// Install the C# / .NET helper library from twilio.com/docs/csharp/install
_27
_27
using System;
_27
using Twilio;
_27
using Twilio.Rest.Api.V2010.Account;
_27
_27
_27
class Program
_27
{
_27
static void Main(string[] args)
_27
{
_27
// Find your Account SID and Auth Token at twilio.com/console
_27
// and set the environment variables. See http://twil.io/secure
_27
string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
_27
string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");
_27
_27
TwilioClient.Init(accountSid, authToken);
_27
_27
var message = MessageResource.Create(
_27
body: "This is the ship that made the Kessel Run in fourteen parsecs?",
_27
from: new Twilio.Types.PhoneNumber("+15017122661"),
_27
to: new Twilio.Types.PhoneNumber("+15558675310")
_27
);
_27
_27
Console.WriteLine(message.Sid);
_27
}
_27
}

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "This is the ship that made the Kessel Run in fourteen parsecs?",
_24
"date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
_24
"date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
_24
"date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+15017122661",
_24
"messaging_service_sid": null,
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "+15558675310",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

Replace the placeholder values for accountSid and authToken with your unique values. You can find these in your Twilio console(link takes you to an external page).

(error)

Danger

Please note: it's okay to hardcode your credentials when getting started, but you should use configuration to keep them secret before deploying to production. We've written blog posts on how to secure user secrets in a .NET Core Web App(link takes you to an external page) and a .NET Core Console App(link takes you to an external page) that should provide you with some good guidance.

If you're working with the .NET Framework, ASP.NET applications should use the built-in configuration system for ASP.NET on the .NET Framework(link takes you to an external page). Other types of .NET applications could use environment variables(link takes you to an external page).

You'll tell Twilio which phone number to use to send this message by replacing the From number with the Twilio phone number you purchased earlier.

Next, specify yourself as the message recipient by replacing the To number with your mobile phone number. Both of these parameters must use E.164 formatting ("+" and a country code, e.g., +16175551212)

We also include the Body parameter, which contains the content of the SMS we're going to send.

Once you've updated the code sample, you can test it out by running it from Visual Studio (with the green triangle "play" button) or with the .NET CLI:


_10
dotnet run

In just a few moments you should receive an SMS!

(warning)

Warning

If you're using a trial account, you'll notice that any messages you send will always begin with "Sent from a Twilio trial account. "Once you upgrade your account, you will no longer see this message. Learn more about sending SMS and MMS messages from a trial account".

Let's take a moment to understand what's going on behind the scenes when you send this request to Twilio.

When Twilio receives your request to send an SMS via the REST API, it will check that you've included a valid Twilio phone number in the From field. Twilio will then either queue the SMS or return this HTTP error in its response to your request.

Outgoing SMS Diagram.

Assuming your request didn't result in any errors, Twilio's HTTP response will include the SID of the new message. This unique identifier will help us reference this message later: in the code above, we printed that SID to the terminal.

Twilio's JSON response includes a robust amount of data about your message. A sample response might look like this:


_24
{
_24
"sid": "SMxxxxxxxxxxxxxxx",
_24
"date_created": "Thu, 09 Aug 2018 17:26:08 +0000",
_24
"date_updated": "Thu, 09 Aug 2018 17:26:08 +0000",
_24
"date_sent": null,
_24
"account_sid": "ACxxxxxxxxxxxxxxxx",
_24
"to": "+15558675310",
_24
"from": "+15017122661",
_24
"messaging_service_sid": null,
_24
"body": "This is the ship that made the Kessel Run in fourteen parsecs?",
_24
"status": "queued",
_24
"num_segments": "1",
_24
"num_media": "0",
_24
"direction": "outbound-api",
_24
"api_version": "2010-04-01",
_24
"price": null,
_24
"price_unit": "USD",
_24
"error_code": null,
_24
"error_message": null,
_24
"uri": "/2010-04-01/Accounts/ACxxxxxxxxx/Messages/SMxxxxxxxxxxxx.json",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACxxxxxxxx/Messages/SMxxxxxxxxxxxxx/Media.json"
_24
}
_24
}

You can access any of these attributes from your .NET code, much like we did when we printed the message.Sid.

Try adding a logging statement like Console.WriteLine(message.Status);. Save the file, then run the code again. You should see the status of your message, "queued", printed to your terminal.

If you receive an error in response from Twilio or never receive the message, you may want to check out these tips for troubleshooting undelivered messages(link takes you to an external page).


_24
{
_24
"sid": "SMxxxxxxxxxxxxxxx",
_24
"date_created": "Thu, 09 Aug 2018 17:26:08 +0000",
_24
"date_updated": "Thu, 09 Aug 2018 17:26:08 +0000",
_24
"date_sent": null,
_24
"account_sid": "ACxxxxxxxxxxxxxxxx",
_24
"to": "+15558675310",
_24
"from": "+15017122661",
_24
"messaging_service_sid": null,
_24
"body": "This is the ship that made the Kessel Run in fourteen parsecs?",
_24
"status": "queued",
_24
"num_segments": "1",
_24
"num_media": "0",
_24
"direction": "outbound-api",
_24
"api_version": "2010-04-01",
_24
"price": null,
_24
"price_unit": "USD",
_24
"error_code": null,
_24
"error_message": null,
_24
"uri": "/2010-04-01/Accounts/ACxxxxxxxxx/Messages/SMxxxxxxxxxxxx.json",
_24
"subresource_uris": {
_24
"media": null
_24
}
_24
}

(information)

Info

If you'd like to track the status of your messages in real-time, you'll need to set up a StatusCallback URL. Learn more in our guide on tracking message delivery.

Send a message to multiple recipients

send-a-message-to-multiple-recipients page anchor

If you want to send a message to several recipients, you could create an list of recipients (or get a list from a database) and iterate through each phone number in the list:


_17
var numbersToMessage = new List<string>
_17
{
_17
"+15558675310",
_17
"+14158141829",
_17
"+15017122661"
_17
};
_17
_17
foreach (var number in numbersToMessage)
_17
{
_17
var message = MessageResource.Create(
_17
body: "Hello from my Twilio number!",
_17
from: new Twilio.Types.PhoneNumber("+15017122662"),
_17
to: new Twilio.Types.PhoneNumber(number)
_17
);
_17
_17
Console.WriteLine($"Message to {number} has been {message.Status}.");
_17
}

This will create a new Message instance for each phone number in the list.

You can send as many messages as you'd like as quickly as you can and Twilio will queue them up for delivery at your prescribed rate limit(link takes you to an external page).

You may find that it's helpful to organize your account and message logs into separate Messaging Services. See our guide on how to set up and send messages from a messaging service for more tips.


Send a message containing media (MMS) in C# and .NET

send-a-message-containing-media-mms-in-c-and-net page anchor

To include media in your Twilio-powered text message, you need to make an addition to the code we wrote above. This time, we need to add the mediaUrl parameter.

Send a Message with an Image URL

send-a-message-with-an-image-url page anchor
C#

_33
// Install the C# / .NET helper library from twilio.com/docs/csharp/install
_33
_33
using System;
_33
using System.Linq;
_33
using Twilio;
_33
using Twilio.Rest.Api.V2010.Account;
_33
_33
_33
class Program
_33
{
_33
static void Main(string[] args)
_33
{
_33
// Find your Account SID and Auth Token at twilio.com/console
_33
// and set the environment variables. See http://twil.io/secure
_33
string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
_33
string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");
_33
_33
TwilioClient.Init(accountSid, authToken);
_33
_33
var mediaUrl = new[] {
_33
new Uri("https://c1.staticflickr.com/3/2899/14341091933_1e92e62d12_b.jpg")
_33
}.ToList();
_33
_33
var message = MessageResource.Create(
_33
body: "This is the ship that made the Kessel Run in fourteen parsecs?",
_33
from: new Twilio.Types.PhoneNumber("+15017122661"),
_33
mediaUrl: mediaUrl,
_33
to: new Twilio.Types.PhoneNumber("+15558675310")
_33
);
_33
_33
Console.WriteLine(message.Sid);
_33
}
_33
}

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "This is the ship that made the Kessel Run in fourteen parsecs?",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+15017122661",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "+15558675310",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

Again, update the From and To parameters to use your Twilio phone number and your mobile phone.

The new mediaUrl parameter in this code tells Twilio where to go to get the media we want to include. This must be a publicly accessible URL: Twilio will not be able to reach any URLs that are hidden or that require authentication. Note that this parameter accepts a list whereby you can send multiple images. In this example, we only want to send one, so we use the helper Promoter.ListOfOne method from the Twilio.Converters namespace.

Just as when you send a simple SMS, Twilio will send data about the message in its response to your request. The JSON response will contain the unique SID and URI for your media resource:


_10
"subresource_uris": {"media": "/2010-04 01/Accounts/ACxxxxxxxx/Messages/SMxxxxxxxxxxxxx/Media.json"}

When the Twilio REST API creates your new Message resource, it will save the image found at the specified mediaUrl as a Media resource. Once created, you can access this resource at any time via the API.

You can print this value from your .NET code to see where the image is stored. Add the following line to the end of your Program.cs file to see your newly provisioned Media URI:


_10
Console.WriteLine(message.SubresourceUris["media"]);

Save the file and run your project. In just a moment you should receive a text message with an image!


You've now successfully sent some messages with the Twilio Programmable SMS API and the Twilio NuGet package.

Check out these in-depth resources to take your programmatic messaging a step further:


Rate this page: