SDKs & libraries

Choose an SDKCopy Anchor Link

The SDKs cover all 56 methods in Activation V2, Rental and Private Email. Choose the language and execution model that fits your application. Alternative API is excluded.

All six SDKs are published alpha releases, with source in the official SMSPVA GitHub repositories. Choose a package below to install it from its public registry. All SDKs use MIT.

Versions and updatesCopy Anchor Link

The published SDKs are alpha releases. Pin a version when you need reproducible installs, and review the repository changelog before upgrading. Python uses 0.1.0a2; JavaScript/TypeScript uses 0.1.0-alpha.2; PHP, Go, C#/.NET and Java use 0.1.0-alpha.1 (with the v prefix in Go commands). These are prerelease versions, not stable releases.

PythonCopy Anchor Link

Install the Python SDK from PyPI. Use --pre to include alpha releases:

python -m pip install --pre smspva-sdk

To pin the current release, use python -m pip install smspva-sdk==0.1.0a2. Source code, the README and issue tracking are in SMSPVA/smspva-python on GitHub.

Use SMSPVA in a synchronous application. This example reads your Activation balance and fetches the current Rental countries and Email providers:

import os
from smspva import SMSPVA

with SMSPVA(os.environ["SMSPVA_API_KEY"]) as client:
    print(client.activation.get_balance())
    print(client.rental.get_countries())
    print(client.email.get_providers())

For an asynchronous application, use AsyncSMSPVA and await the same methods:

import asyncio
import os
from smspva import AsyncSMSPVA

async def main():
    async with AsyncSMSPVA(os.environ["SMSPVA_API_KEY"]) as client:
        print(await client.activation.get_balance())
        print(await client.rental.get_countries())
        print(await client.email.get_providers())

asyncio.run(main())

The context manager closes the connection pool for you. If you manage the client yourself, call close() or await aclose() when you finish.

JavaScript and TypeScriptCopy Anchor Link

Install the JavaScript and TypeScript SDK from npm. The alpha tag selects the latest alpha release:

npm install smspva-sdk@alpha

To pin the current release, use npm install [email protected]. Source code, the README and issue tracking are in SMSPVA/smspva-js on GitHub.

import { SMSPVA } from 'smspva-sdk';

const client = new SMSPVA({ apiKey: process.env.SMSPVA_API_KEY });

console.log(await client.activation.getBalance());
console.log(await client.rental.getCountries());
console.log(await client.email.getProviders());

The same code works in JavaScript. For CommonJS, import with const { SMSPVA } = require('smspva-sdk'). Run the SDK on your server and keep the API key out of browser code.

PHPCopy Anchor Link

Install the PHP SDK from Packagist with Composer:

composer require "smspva/sdk:^0.1@alpha"

To pin this release, use composer require smspva/sdk:0.1.0-alpha.1. Source code, the README and issue tracking are in SMSPVA/smspva-php on GitHub.

<?php
declare(strict_types=1);
require __DIR__ . "/vendor/autoload.php";

use SMSPVA\Client;

$client = new Client(getenv("SMSPVA_API_KEY") ?: null);
print_r($client->activation->getBalance());
print_r($client->rental->getCountries());
print_r($client->email->getProviders());

PHP methods accept parameter arrays with generated PHPDoc shapes. Responses are associative arrays. The client is synchronous and requires the cURL extension.

GoCopy Anchor Link

Install the Go SDK from its tagged module:

go get github.com/SMSPVA/[email protected]

Source code, the README and issue tracking are in SMSPVA/smspva-go on GitHub. The SDK uses only the standard library.

The Go SDK is a versioned GitHub module. pkg.go.dev displays its README and generated package documentation; it is not a separate upload destination. No pkg.go.dev account is needed to install it. New versions are identified by Git tags in the official repository.

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    smspva "github.com/SMSPVA/smspva-go"
)

func printResult(response smspva.Response, err error) {
    if err != nil { log.Fatal(err) }
    fmt.Println(string(response.Body))
}

func main() {
    client, err := smspva.New(smspva.Options{APIKey: os.Getenv("SMSPVA_API_KEY")})
    if err != nil { log.Fatal(err) }
    defer client.CloseIdleConnections()
    ctx := context.Background()
    printResult(client.Activation.GetBalance(ctx))
    printResult(client.Rental.GetCountries(ctx))
    printResult(client.Email.GetProviders(ctx))
}

Save the program as main.go and run go run .. Methods take a context.Context, typed parameter structs where needed, and return the unchanged JSON in Response.Body.

C# / .NETCopy Anchor Link

Install the .NET SDK from NuGet. Source, the README and issue tracking are in SMSPVA/smspva-dotnet on GitHub:

dotnet add package Smspva.Sdk --version 0.1.0-alpha.1

using System;
using Smspva;

using var client = new SmspvaClient(Environment.GetEnvironmentVariable("SMSPVA_API_KEY"));
Console.WriteLine(await client.Activation.GetBalanceAsync());
Console.WriteLine(await client.Rental.GetCountriesAsync());
Console.WriteLine(await client.Email.GetProvidersAsync());

C# methods are asynchronous and accept a CancellationToken. Request records are typed; responses are JsonElement values.

JavaCopy Anchor Link

Install the Java SDK from Maven Central by adding this dependency to your application’s pom.xml:

<dependency>
  <groupId>com.smspva</groupId>
  <artifactId>smspva-sdk</artifactId>
  <version>0.1.0-alpha.1</version>
</dependency>

import com.smspva.sdk.SmsPva;

public class Example {
    public static void main(String[] args) {
        try (SmsPva client = new SmsPva(System.getenv("SMSPVA_API_KEY"))) {
            System.out.println(client.activation().getBalance());
            System.out.println(client.rental().getCountries());
            System.out.println(client.email().getProviders());
        }
    }
}

Source code, the README and issue tracking are in SMSPVA/smspva-java on GitHub. Java methods are synchronous, accept typed Requests records, and return JsonNode. This alpha has no Java async wrapper or polling helper.

Parameters and responsesCopy Anchor Link

Choose country, service and provider codes from the current reference lists. For example, call email.get_providers() in Python or email.getProviders() in JavaScript to load the providers, then pass the chosen pcode to get_data(pcode=...) or getData({ pcode: ... }). Public reference methods work without an API key and never send the client's key.

The SDKs preserve documented HTTP methods, wire parameter names, response codes and JSON value types. Python and JavaScript include generated response types. PHP returns associative arrays, Go returns raw JSON in Response.Body, C# uses JsonElement, and Java uses JsonNode. Their request arguments are documented or typed for each language.

For Rental's multi-service count method, provide dtype and dcount explicitly. The SDK requires both because the API documentation warns against relying on the backend defaults for this method.

Waiting for SMS and handling errorsCopy Anchor Link

Activation's receive_sms / receiveSms returns the original pending response for HTTP 202 and SMS_NOT_YET_RECEIVED. Check it with is_pending / isPending. Email creation likewise returns the original status=2 no-stock result; use is_no_stock / isNoStock to recognise it.

For repeated SMS checks, use activation.wait_for_sms in Python or activation.waitForSms in JavaScript. Save the order's expiry when you obtain the number, then pass that same deadline as expires_at (Unix seconds) or expiresAt (Unix milliseconds). The helper waits at least five seconds between pending responses and stops at the deadline or on an error. It never creates or cancels orders. Receiving a new SMS can trigger payment.

A single receive_sms / receiveSms call makes one HTTP request. The Python and JavaScript waiting helpers send the first request immediately, then wait five seconds after each pending response before checking again. Set interval=15 in Python or intervalMs: 15_000 in JavaScript for a 15-second pause. This minimum interval is a helper policy, not an API-wide rate limit. await waits for the helper result while allowing other asynchronous tasks to run during requests and pauses; the synchronous Python client blocks the calling thread.

Python, JavaScript and PHP report API failures through ApiError; C# and Java use ApiException, and Go returns an APIError. These keep the HTTP status, API code and original response. Protocol and transport errors are separate. C# supports cancellation tokens, and Go supports context cancellation.

No request is retried automatically. If a paid or state-changing request loses its connection, its outcome may be unknown. Check your current orders before repeating it to avoid a duplicate purchase. A GET method can still change state or trigger a charge.

The default timeout is 30 seconds. Python applies it to each HTTPX network operation; JavaScript applies it to the whole request, including reading the response body. Override it with timeout in Python or timeoutMs in JavaScript. JavaScript also accepts an AbortSignal through the signal option.

PHP, Go and C# also bound the complete request by default. Java uses network-operation timeouts, like Python, rather than a strict whole-response deadline. Java and PHP are synchronous. Check the SDK README for timeout options and error types in your language.

You can continue using the HTTP examples alongside the SDKs. Each API method page remains the reference for its parameters, response codes and important warnings.