SMSTunnel for .NET

dotnet add package SmsTunnel
# in ASP.NET Core, worker services and other apps with dependency injection:
dotnet add package SmsTunnel.Extensions.DependencyInjection

using SmsTunnel;

using var sms = new SmsTunnelClient(Environment.GetEnvironmentVariable("SMSTUNNEL_API_KEY")!);

SendResult result = await sms.SendSmsAsync("+14155550123", "Your order #1042 has shipped.");

Console.WriteLine(result.MessageId); // keep it to look up the status later

SendResult result = await sms.SendSmsAsync(
    "+14155550123",                    // international format; one number per call
    "See you at 10:30.",               // up to 1600 characters
    new SendOptions
    {
        DeviceId = "6aea3248fedd7cccac9abf42",       // the phone that sends it (Phones → Copy); leave it out to let SMSTunnel pick one of yours
        DefaultCountryCode = "+40",                  // completes numbers written without + or 00, like 0721 123 456
        IdempotencyKey = "appointment-981-reminder", // makes a retry safe, see below
    },
    cancellationToken);

result.MessageId; // string
result.Queued;    // true when no phone of yours was online: the text waits and goes out when one is back
result.Branded;   // true when the Free plan added its short line to the text
result.Replayed;  // true when this is the stored answer to an earlier call with the same IdempotencyKey

await sms.SendSignInCodeAsync("+14155550123", "Your sign-in code is 482913");

MessageStatus status = await sms.GetMessageStatusAsync(result.MessageId); // needs sms:read

status.State;        // Pending, Sent, Delivered, Failed or Unconfirmed
status.IsFinal;      // true once it won't change: Delivered, Failed or Unconfirmed
status.SentAt;       // DateTimeOffset?
status.ErrorMessage; // why it failed

foreach (Phone phone in await sms.GetPhonesAsync())
{
    Console.WriteLine($"{phone.Name}: {(phone.IsOnline ? "online" : "offline")} ({phone.Id})");
}

Usage usage = await sms.GetUsageAsync();
usage.Plan;                 // "free", "twofa" (Starter), "standard", "pro" (Professional) or "enterprise"
usage.Used.SmsClean;        // texts sent today
usage.Remaining.SmsClean;   // texts left today; null means no limit
usage.Remaining.TwoFaClean; // sign-in codes left today

ReceivedTextPage page = await sms.GetReceivedTextsAsync(new ReceivedTextsQuery
{
    Since = DateTimeOffset.UtcNow.AddDays(-1),
    Phone = "+14155550123", // only from this sender
    Limit = 20,             // 1 to 100
    Page = 1,
});

foreach (ReceivedText text in page.Texts) // newest first
{
    Console.WriteLine($"{text.ReceivedAt:t} {text.Sender}: {text.Message}");
}

page.HasMore; // ask for the next page

builder.Services.AddSmsTunnel();

// appsettings.json: everything except the key, which stays out of the repository
{
  "SmsTunnel": {
    "DefaultCountryCode": "+40", // optional
    "Timeout": "30"              // optional: seconds, or a time span such as 00:00:30
  }
}

dotnet user-secrets set "SmsTunnel:ApiKey" "<your key>"   # while developing
export SmsTunnel__ApiKey="<your key>"                      # on a server, or your host's secret store

app.MapPost("/orders/{id:int}/shipped", async (int id, ShopDb db, ISmsTunnelClient sms, ILogger<Program> log, CancellationToken ct) =>
{
    Order order = await db.Orders.FindAsync([id], ct) ?? throw new BadHttpRequestException("No such order.");
    order.Status = OrderStatus.Shipped;
    await db.SaveChangesAsync(ct);

    try
    {
        await sms.SendSmsAsync(order.Phone, $"Your order #{order.Id} has shipped.",
            new SendOptions { IdempotencyKey = $"order-{order.Id}-shipped" }, ct);
    }
    catch (SmsTunnelException error)
    {
        log.LogWarning(error, "The shipping text for order {OrderId} did not go out", order.Id);
    }

    return Results.NoContent();
});

public interface ISmsSender
{
    Task SendSmsAsync(string phoneNumber, string message, CancellationToken cancellationToken = default);
}

public sealed class SmsTunnelSmsSender(ISmsTunnelClient smsTunnel) : ISmsSender
{
    // Identity's phone codes are 6 digits on their own: they go out as sign-in codes, with their own allowance.
    public Task SendSmsAsync(string phoneNumber, string message, CancellationToken cancellationToken = default) =>
        smsTunnel.SendSignInCodeAsync(phoneNumber, message, cancellationToken: cancellationToken);
}

builder.Services.AddSmsTunnel();
builder.Services.AddTransient<ISmsSender, SmsTunnelSmsSender>();

string code = await userManager.GenerateChangePhoneNumberTokenAsync(user, phoneNumber);
await smsSender.SendSmsAsync(phoneNumber, $"Your verification code is {code}");
// later, with the code the user typed:
IdentityResult result = await userManager.ChangePhoneNumberAsync(user, phoneNumber, typedCode);

SignInResult result = await signInManager.PasswordSignInAsync(email, password, isPersistent: false, lockoutOnFailure: true);
if (result.RequiresTwoFactor)
{
    IdentityUser user = (await userManager.FindByNameAsync(email))!;
    string code = await userManager.GenerateTwoFactorTokenAsync(user, TokenOptions.DefaultPhoneProvider);
    await smsSender.SendSmsAsync(user.PhoneNumber!, $"Your sign-in code is {code}");
}
// next request, with the code the user typed:
SignInResult signedIn = await signInManager.TwoFactorSignInAsync(TokenOptions.DefaultPhoneProvider, typedCode, isPersistent: false, rememberClient: false);

try
{
    await sms.SendSmsAsync(phoneNumber, text, new SendOptions { IdempotencyKey = textId }, ct);
}
catch (SmsTunnelRateLimitException error) when (error.RetryAfter is TimeSpan wait)
{
    await Task.Delay(wait, ct); // then try again, with the same IdempotencyKey
}
catch (SmsTunnelPermissionException error) when (error.ErrorCode == SmsTunnelErrorCodes.PermissionRequired)
{
    log.LogError("The SMSTunnel key lacks {Permission}", error.Permission);
}
catch (SmsTunnelException error)
{
    log.LogWarning(error, "The text did not go out");
}

var handler = new SocketsHttpHandler { AllowAutoRedirect = false }; // the key is never sent to another address
var http = new HttpClient(handler);

var sms = new SmsTunnelClient(http, new SmsTunnelClientOptions
{
    ApiKey = Environment.GetEnvironmentVariable("SMSTUNNEL_API_KEY")!,
    DefaultCountryCode = "+40",            // for numbers written without + or 00; a text's own wins
    Timeout = TimeSpan.FromSeconds(15),    // per call; the default is 30 seconds
    // BaseUrl = new Uri("http://127.0.0.1:3141"), // a test server; the default is https://smstunnel.io
});