SMSAPI C# client

Client library for the SMSAPI messaging platform. Works with smsapi.io, smsapi.pl and smsapi.com accounts.

Requirements

• .NET 6.0 or newer (net6.0, net7.0, net8.0, net9.0, net10.0)

Dependencies

Installed automatically by NuGet:

• Newtonsoft.Json >= 13.0.3

No other third-party packages are required. HTTP communication uses the built-in System.Net.Http.HttpClient.

Installation

dotnet add package SMSAPI.pl

or in Package Manager Console:

Install-Package SMSAPI.pl

Quick start

using SMSApi.Api;

var client = new ClientOAuth("token");
var features = new Features(client);

var result = features.SMS()
    .ActionSend("4850010010", "Hello world")
    .SetSender("Test")
    .Execute();

Console.WriteLine($"Sent: {result.Count}");

More examples for every feature are in the examples/ directory.

Authentication

Only OAuth bearer tokens are supported. Generate a token in the SMSAPI panel (smsapi.pl / smsapi.com) and pass it to ClientOAuth:

var client = new ClientOAuth("token");

Basic (username/password) authentication was removed in 3.0.

How to pick a service?

Features (and every *Factory) accepts a ProxyAddress. Default is smsapi.io.

var features = new Features(client);                          // smsapi.io (default)
var features = new Features(client, ProxyAddress.SmsApiPl);   // api.smsapi.pl
var features = new Features(client, ProxyAddress.SmsApiCom);  // api.smsapi.com

Backup endpoints ProxyAddress.BackupSmsApiPl and ProxyAddress.BackupSmsApiCom are available as well.

Features

Every feature is reached through an extension method on Features:

Feature	Accessor	Examples
SMS (send, get status, delete scheduled, fallback, templates)	features.SMS()	examples/sms
MMS	features.MMS()	examples/mms
VMS (text-to-speech, audio file)	features.VMS()	examples/vms
HLR lookups	features.HLR()	examples/hlr
MFA codes	features.MFA()	examples/mfa
Sender names	features.Sendernames()	examples/sendernames
Short URLs	features.ShortUrl()	examples/shortUrl
Contacts, groups, fields	features.Contacts()	examples/contacts
Subusers	features.Subusers()	examples/subusers
Blacklist	features.Blacklist()	examples/blacklist
Opt-out	features.OptOut()	examples/optOut
Profile, points	features.Profile()	examples/profile
Prices	features.Prices()	examples/profile/prices
Ping	features.Ping()	examples/ping

Listings support pagination through Limit / Offset — see examples/Pagination.cs.

Async

Every action can be executed asynchronously:

var result = await features.SMS()
    .ActionSend("4850010010", "Hello world")
    .ExecuteAsync(cancellationToken);

Custom HttpClient and proxy

By default the library creates its own HttpClient. To reuse your own instance (e.g. configured with a web proxy, timeouts or IHttpClientFactory), pass it to Features:

var httpClient = new HttpClient(new HttpClientHandler
{
    Proxy = new WebProxy("http://proxy.example.com:8080"),
});

var features = new Features(client, httpClient, ProxyAddress.SmsApiPl);

To point the client at a different base URL (e.g. a test environment), build the transport yourself:

var proxy = new ProxyHTTP("https://api.example.com", httpClient);
var features = new Features(client, proxy);

Error handling

All API errors derive from SmsapiException, which exposes the error Code and, where available, the raw API Response.

try
{
    var result = features.SMS()
        .ActionSend("4850010010", "Hello world")
        .Execute();
}
catch (ActionException e)
{
    // Action error, e.g. invalid sender name, empty message
    Console.WriteLine($"{e.Code}: {e.Message}");
}
catch (ClientException e)
{
    // Client error, e.g. 101 invalid token, 103 insufficient credits
    // (full list of codes in the SMSAPI docs: https://www.smsapi.pl/docs)
    Console.WriteLine($"{e.Code}: {e.Message}");
}
catch (HostException e)
{
    // Server error or malformed API response (code -1, raw body in e.Response)
    Console.WriteLine($"{e.Code}: {e.Message}");
}
catch (ProxyException e)
{
    // Communication problem between the client and the server
    Console.WriteLine(e.Message);
}

REST endpoints (contacts, sender names, short URLs, subusers, opt-out, blacklist, MFA, HLR) additionally throw typed exceptions from smsapi.Api.Response.REST.Exception — ValidationException (with ValidationErrors), NotFoundException (base for feature-specific ones like OptOutNotFoundException), UnauthorizedException, AccessForbiddenException, TooManyRequestsException, ServiceUnavailableException — and feature-specific ones such as ContactAlreadyExistsException or ShortUrlWithNameAlreadyExistsException.

Upgrading from 2.x

See CHANGELOG.md for the full list of breaking changes in 3.0.

License

Apache 2.0 License