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.

1. Set the required environment variables (see above).
2. 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.