PostaGuvercini.NET.SMS 0.0.6

PostaGuvercini.NET.SMS

A C# library for sending SMS messages using the Posta Guvercini SMS API.

Features

• Send OTP, informational, and advertisement SMS messages
• Personalize messages for each receiver
• Track message delivery status
• Check account credit
• Advanced options: scheduling, expiration, SIM card check, dealer code, and more
• Supports dependency injection
• Asynchronous methods with cancellation support
• Detailed error handling with exceptions
• Supports .NET Standard 2.0 and above

Installation

Install via NuGet:

dotnet add package PostaGuvercini.NET.SMS

Usage

Initialization

using PostaGuvercini.NET.SMS;

var sms = new SMS("API_DOMAIN", "YOUR_PUBLIC_KEY", "YOUR_PRIVATE_KEY");

Or with options:

var sms = new SMS(new SMSOptions {
    Domain = "API_DOMAIN",
    PublicKey = "YOUR_PUBLIC_KEY",
    PrivateKey = "YOUR_PRIVATE_KEY",
    Timeout = TimeSpan.FromSeconds(30)
});

Or can be injected via dependency injection:

services.AddSMS(ServiceLifetime.Transient, (provider) => 
    new SMSOptions {
        Domain = "API_DOMAIN",
        PublicKey = "YOUR_PUBLIC_KEY",
        PrivateKey = "YOUR_PRIVATE_KEY",
        Timeout = TimeSpan.FromSeconds(30)
    });

// Later in your code, you can retrieve the ISMS instance or inject it into your classes:
ISMS sms = provider.GetRequiredService<ISMS>();

// Or inject it directly into your class constructor
public class MyController : ControllerBase
{
    private readonly ISMS _sms;

    public MyController(ISMS sms)
    {
        _sms = sms;
    }

    // Use _sms in your actions
}

API Reference

• From(senderId): Set sender ID (required)
• Text(text, encoding): Set message text and encoding
• To(mobileNumber, ...): Add receiver(s) (Multiple overloads available)
• CreditAsync(): Check account credit
• StatusAsync(messageId): Check delivery status of a message
• Purpose(purpose): Set message purpose (OTP, INFORMATIONAL, ADVERT)
• Label(label): for tracking and reporting
• ReferenceId(referenceId): to set reference ID of message for your internal tracking
• SendTime(dateTime): to schedule messages for future delivery
• ExpireTime(dateTime): to set message validity period
• CheckSimCard(): Enable SIM card change check (OTP only)
• DealerCode(code): Set dealer code
• SendAsync(): Send message (generic), purpose must be set before calling
• SendOtpAsync(): Send OTP message
• SendInformationalAsync(): Send informational message
• SendAdvertAsync(): Send advertisement message

Notes

• Sender ID must be pre-registered with the SMS provider.
• OTP messages: max 10 receivers per request.
• Regular messages: max 10,000 receivers per request.
• Personalization is supported using {{1}}, {{2}}, etc. in the text. (Order of the placeholders matters. Must be exactly the same as the number of parameters provided for each receiver.)
• All methods are asynchronous and support cancellation tokens.
• Exceptions are thrown for errors; handle them appropriately.
• HTTP Timeout can be configured in SMSOptions or by constructor.
• For advanced usage, refer to the API documentation of Posta Guvercini.

Examples

Sending a Simple SMS

await sms
    .From("SENDERID")
    .Text("Hello, this is a test message!")
    .To(905555555555)
    .SendInformationalAsync();

Sending Personalized OTP SMS

await sms
    .From("SENDERID")
    .Text("Hello {{1}}, your login code is {{2}}")
    .To(905550000000, ["John Doe", "123456"])
    .To(905551111111, ["Alex Doe", "567890"])
    .SendOtpAsync();

Sending Bulk SMS

await sms
    .From("SENDERID")
    .Text("This is a bulk message to multiple recipients.")
    .Label("My Bulk Message")
    .To([ 905550000000,
          905551111111,
          905552222222 ])
    .SendAdvertAsync();

Sending Different Texts to Multiple Receivers

await sms
    .From("SENDERID")
    .To(905550000000, text: "Hello John, your code is 123456")
    .To(905551111111, text: "Hello Alex, your code is 567890")
    .SendInformationalAsync();

var receivers = [
    new DataMessageReceiver(905550000000, "Hello John, your promotion code is 123456"),
    new DataMessageReceiver(905551111111, "Hello Alex, your promotion code is 567890"),
    new DataMessageReceiver(905552222222, "Hello Jane, your promotion code is 789012")
];

await sms
    .From("SENDERID")
    .To(receivers)
    .SendAdvertAsync();

Checking Message Status

var status = await sms.StatusAsync("MESSAGE_ID");

Checking Credit

var credit = await sms.CreditAsync();

For more information, contact Posta Guvercini support.