smsir-rust 0.1.0

A fast, secure, and modular Rust library for interacting with the SMS.ir SMS API, with built-in error handling and a clean, idiomatic interface.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

# smsir-rust

[![crates.io](https://img.shields.io/crates/v/smsir-rust.svg)](https://crates.io/crates/smsir-rust) [![docs.rs](https://docs.rs/smsir-rust/badge.svg)](https://docs.rs/smsir-rust/)

`smsir-rust` is a secure and fast library for communicating with the [SMS.ir](https://www.sms.ir) SMS web service in the Rust programming language. This library is developed with modular design and error handling in mind.

## [راهنما به زبان فارسی](README.fa.md)

## 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

```bash
cargo add smsir-rust
```

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

```toml
smsir-rust = "0.1.0"
```

Then:

```powershell
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

```rust
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

```rust
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

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

### Get Credit

```rust
let credit = service.get_credit();
```

### Get Sender Lines

```rust
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:

```bash
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.