smsir-rust

smsir-rust is a secure and fast library for communicating with the SMS.ir SMS web service in the Rust programming language. This library is developed with modular design and error handling in mind.

راهنما به زبان فارسی

Features

Send single and bulk SMS
Send peer-to-peer SMS
Send verification (OTP) messages using templates
Schedule and delete scheduled messages
Retrieve credit and sender numbers
Receive incoming messages (new, live, archived)
Get reports of sent messages
Retrieve list of sent packs
Error handling and extensibility

Installation

cargo add smsir-rust

Or manually add the following to the [dependencies] section of your Cargo.toml file:

smsir-rust = "0.1.0"

Then:

cargo build

Usage Guide

First, obtain your API key from the SMS.ir panel and use it in your code.

Example: Send a Single SMS

use smsir_rust::service::SmsService;

let api_key = "YOUR_API_KEY";
let service = SmsService::new(api_key);
let result = service.send_single(
    "Sender number",
    "Message text",
    "Receiver number"
);
match result {
    Ok(response) => println!("Sent successfully: {:?}", response),
    Err(e) => eprintln!("Error: {}", e),
}

Example: Send Bulk SMS

let mobiles = vec!["09123456789", "09121234567"];
let result = service.send_bulk(
    "Sender number",
    "Message text",
    &mobiles,
    None // For immediate sending
);

Example: Send Verification SMS with Template

let params = vec![("Code", "12345")];
let result = service.send_verify(
    "Receiver number",
    100000, // Template ID
    &params
);

Get Credit

let credit = service.get_credit();

Get Sender Lines

let lines = service.get_lines();

Library Structure

service: Main API interaction methods
result: Response data structures
error: Error handling

Running Integration Tests

To run integration tests and ensure the library functions properly, you need to set a few environment variables with real values. These variables are required for different tests related to sending SMS and receiving reports:

SMSIR_API_KEY: API key from the SMS.ir panel
SMSIR_TEST_MOBILE: Valid mobile number for testing (e.g. 09123456789)
SMSIR_TEST_SENDER: Active sender number from your panel (e.g. 3000...)
SMSIR_TEST_TEMPLATE_ID: Template ID for OTP message (e.g. 123456)
SMSIR_TEST_PACK_ID: A valid pack_id for testing scheduled message deletion
SMSIR_TEST_MSG_ID: A valid msg_id for testing message report

Note: If any of these variables is not set, the corresponding test will not run and an appropriate message will be shown.

Set the required environment variables (see above).
Run:

cargo test --test integration

If the tests pass successfully, you will see output like the following:

running 8 tests
test integration::test_get_credit ... ok
test integration::test_bulk_send ... ok
...

test result: ok. 8 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

If an error occurs, an error message will be displayed. Please make sure all environment variables are set with valid values and you are connected to the internet.

smsir-rust 0.1.0