An async Rust client for the Kavenegar SMS, OTP and voice-call API.
Warning
This crate is under active development. The API may change between
0.x releases, There are a few things that I need to check and implement.
If a response fails to decode, please
open an issue with the raw
body — Error::Decode includes it.
- All 32 endpoints from the REST docs
- Typed status codes that never break when Kavenegar adds a new one
- Mistakes caught before you spend a request
- No date or TLS baggage —
rustlsby default, nothing from the system
- Install
- Get an API key
- Quick start
- Usage
- Handling errors
- Pagination
- All methods
- Cargo features
- Testing
- Security
- Things worth knowing
- License
cargo add kavenegar
cargo add tokio --features macros,rt-multi-threadOr add it by hand:
[dependencies]
kavenegar = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }Needs Rust 1.88 or newer.
Sign up at kavenegar.com. You can then find your account's API KEY in the panel under Settings › Security Settings.
Keep it out of your source code. Read it from the environment instead:
export KAVENEGAR_API_KEY=your-key-hereuse kavenegar::Kavenegar;
#[tokio::main]
async fn main() -> Result<(), kavenegar::Error> {
let client = Kavenegar::new(std::env::var("KAVENEGAR_API_KEY").unwrap());
let sent = client.sms().send(["09177788155"], "Hello!").await?;
println!("queued as {}", sent[0].message_id);
Ok(())
}Build the client once and use it everywhere. Copy it wherever you like — the copies share one connection pool, so keep it in your application state rather than making a new one per request.
Calls with optional parameters return a builder. Set what you need, then
await the builder itself — there is no separate send() step.
// Simple.
let sent = client.sms().send(["09177788155"], "Hello!").await?;
// With options.
use kavenegar::MessageType;
let sent = client
.sms()
.send(["09177788155", "09111234567"], "Your code: 1234")
.sender("10004346") // a specific line
.message_type(MessageType::Flash)
.tag("signup") // groups it in your reports
.await?;
// Media on a messenger line, or a sending policy instead of one line.
let sent = client
.sms()
.send(["09177788155"], "Your invoice")
.media_id(&media.id) // from client.media().upload(..)
.policy("night-flow") // a sending policy defined in your panel
.await?;
// A different message per recipient, in one call.
let sent = client
.sms()
.send_array(
["09177788155", "09131234567"],
["First message", "Second message"],
)
.sender("10004346") // required here; or .senders([...]) per message
.await?;Use this rather than a plain SMS for sign-in codes. It sends a template you registered in the panel, needs no dedicated line, and still reaches people who have opted out of bulk messaging.
let sent = client
.verify()
.lookup("09177788155", "verify-login", "48391")
.await?;Your template holds the wording; you supply only the token:
Your login code is %token
A template can take up to five substitutions:
let sent = client
.verify()
.lookup("09177788155", "order-shipped", "48391")
.token2("Shiraz")
.token10("Goudarz Jafari") // token10 allows 5 spaces, token20 allows 8
.await?;To read it out over a phone call instead:
use kavenegar::VerifyChannel;
let sent = client
.verify()
.lookup("09177788155", "verify-login", "48391")
.channel(VerifyChannel::Call)
.await?;Sending is asynchronous, so the status right after sending is "queued". Check back with the message id:
let statuses = client.sms().status([sent.message_id]).await?;
for m in statuses {
println!("{}: {}", m.receptor, m.status);
if m.status.is_delivered() {
println!(" arrived");
} else if m.status.is_final_failure() {
println!(" failed for good, stop polling");
} else if m.status.is_pending() {
println!(" still on its way");
}
}let calls = client
.call()
.text_to_speech(["09177788155"], "Your order has shipped")
.await?;let info = client.account().info().await?;
println!("{} Rials remaining", info.remaining_credit);// Reads up to 100 unread messages and marks them read, so each comes back once.
let received = client.sms().receive("3000202030").await?;
// The same, 200 per page, with a date window and page counters.
// This marks what it returns as read too.
let page = client.sms().inbox_paged("3000202030").unread().await?;People who reply with a stop keyword are blocked on the line they replied to, so every method here takes the line number first.
let page = client.line().blocked("10004346").await?;
let results = client.line().block("10004346", ["09177788155"]).await?; // up to 200
let done = client.line().unblock("10004346", ["09177788155"]).await?; // up to 50
println!("{}", done.message);
let results = client.line().is_blocked("10004346", ["09177788155"]).await?;
if results[0].status.is_blocked() {
println!("do not send to this number");
}For messenger lines. Images up to 10 MB, MP4 video up to 20 MB and 60 seconds.
let bytes = tokio::fs::read("photo.jpg").await?;
let media = client.media().upload("photo.jpg", bytes).await?;
println!("uploaded as {}", media.id);
let page = client.media().list().await?;
let class="pl-kos">.media().get(&media.id).await?;
client.media().delete(&media.id).await?;Manage verification templates from code instead of the panel.
use kavenegar::{SendMethod, SourceType};
let template = client
.verify()
.add_template("LoginOtp", SourceType::Website, SendMethod::Sms)
.text_message("Your login code is %token")
.await?;
let page = client.verify().templates().await?;
let class="pl-kos">.verify().template(template.id).await?;
let copy = client.verify().clone_template("LoginOtpV2").from_id(template.id).await?;
client.verify().delete_template(template.id).await?;Resellers can act on a customer's templates by naming the sub-account:
let page = client
.verify()
.templates()
.sub_account_api_key("the-customers-key")
.await?;Kavenegar reports most problems with HTTP 200 and a status code in the body, so
match on Error::Api rather than the HTTP status.
use kavenegar::{ApiStatus, Error};
match client.sms().send(["09177788155"], "Hello").await {
Ok(sent) => println!("queued as {}", sent[0].message_id),
Err(Error::Api(e)) if e.status() == ApiStatus::InsufficientCredit => {
eprintln!("out of credit: {}", e.message());
}
Err(Error::Api(e)) if e.status() == ApiStatus::InvalidReceptor => {
eprintln!("bad phone number");
}
Err(e) if e.is_retryable() => {
eprintln!("temporary problem, try again: {e}");
}
Err(e) => return Err(e),
}Every documented code has a named variant. Codes Kavenegar adds later arrive as
ApiStatus::Other(i32) instead of failing to parse, so your build keeps
working.
is_retryable() is true only for genuinely transient failures — a busy server,
a rate limit, a network timeout. It is never true for a bad key or an empty
balance, where retrying would just repeat the failure.
Some mistakes are caught before a request goes out at all, so they cost you nothing:
// Two recipients but one message.
let err = client
.sms()
.send_array(["09121234567", "09131234567"], ["only one"])
.sender("10004346")
.await;
// -> InvalidParameter { parameter: "messages", .. }
// A "phone number" that is really two, typed into your sign-up form.
let err = client.verify().lookup("09121234567,09131234567", "verify-login", "4839").await;
// -> InvalidParameter { parameter: "receptor", .. }Listing calls return a Page<T>. It behaves like a slice and carries the
counters you need to walk the rest:
let mut page = client.verify().templates().await?;
loop {
for template in &page {
println!("{}", template.name);
}
let Some(next) = page.next_page() else { break };
page = client.verify().templates().page(next).await?;
}| Service | Methods |
|---|---|
sms() |
send, send_array, status, status_by_local_id, status_by_receptor, select, select_outbox, latest_outbox, count_outbox, cancel, receive, inbox_paged, count_inbox |
verify() |
lookup, templates, template, add_template, update_template, clone_template, delete_template |
call() |
text_to_speech |
account() |
info, config, update_config |
line() |
blocked, block, unblock, is_blocked |
media() |
upload, list, get, delete |
utils() |
server_time |
Everything is on by default, so kavenegar = "0.1" just works.
To compile only what you use, turn the defaults off and name the services you want. Keep a TLS backend in the list, or nothing will connect:
kavenegar = { version = "0.1", default-features = false, features = ["sms", "verify", "rustls-tls"] }| Feature | Default | Enables |
|---|---|---|
full |
✅ | Every service below |
sms |
✅ | client.sms() |
verify |
✅ | client.verify() |
call |
✅ | client.call() |
account |
✅ | client.account() |
line |
✅ | client.line() |
media |
✅ | client.media() — adds multipart |
utils |
✅ | client.utils() |
rustls-tls |
✅ | TLS through rustls, no system OpenSSL |
native-tls |
❌ | TLS through the platform's own stack |
Some ready-made combinations:
# OTP only — the smallest useful build.
kavenegar = { version = "0.1", default-features = false, features = ["verify", "rustls-tls"] }
# Everything except media, which drops the multipart dependency.
kavenegar = { version = "0.1", default-features = false, features = [
"sms", "verify", "call", "account", "line", "utils", "rustls-tls",
] }
# Full, on the platform TLS stack instead of rustls.
kavenegar = { version = "0.1", default-features = false, features = ["full", "native-tls"] }To be straight about it: dropping media is the only choice that removes a
real dependency. The other flags mainly trim compile time. If you have no
particular reason to trim, keep the default.
Check your account before anything else. This is read-only and free:
export KAVENEGAR_API_KEY=your-key
cargo run --example diagnoseIt probes the clock, credit, templates, outbox and media library, then tells you in plain terms what works and what to fix:
server clock ... ok — 03/09/2026 11:42:17 ق.ظ (unix 1788500537)
account info ... ok — 250000 Rials, type `master`, expires 1798500537
verify templates ... ok — 2 registered
recent outbox ... skipped — needs an IP allowlist entry (407)
media library ... ok — 0 file(s)
Offline tests need no key and no network. They run a stub HTTP server in-process:
cargo testLive tests talk to the real API and are #[ignore]d so they never run by
accident. The read-only ones cost nothing — start there:
export KAVENEGAR_API_KEY=your-key
cargo test --test live -- --ignored readonly --nocaptureThat checks the server clock, your credit, your templates, and that a bad key is reported properly.
The sending tests deliver real messages and spend credit:
export KAVENEGAR_TEST_RECEPTOR=09177788155
export KAVENEGAR_TEST_SENDER=10004346 # optional
export KAVENEGAR_TEST_TEMPLATE=verify-login # optional
cargo test --test live -- --ignored sending --nocapture --test-threads=1A test whose variable is missing skips itself with a note rather than failing.
The examples are the quickest manual check:
cargo run --example send_sms -- 09177788155 "Hello"
cargo run --example send_otp -- 09177788155 verify-loginEverything CI runs, if you want it locally:
cargo fmt --all --check
cargo clippy --all-features --all-targets -- -D warnings
cargo test --all-features
cargo doc --all-features --no-depsThe API key is the asset here, and Kavenegar puts it in the URL path rather than a header. A URL travels further than a header does, so this crate:
- Keeps the URL out of error messages.
reqwestembeds the request URL in its own errors; passing those through would write your key into every log line that formats an error. Transport failures are re-wrapped to keep the diagnosis and drop the URL. - Redacts the key from
Debugoutput and from any response body kept for diagnostics. - Requires TLS 1.2+, on both TLS backends.
- Sanitises Kavenegar's error text before it reaches
Display, so a newline or terminal escape in it cannot forge a log line. - Refuses plain HTTP to non-loopback hosts, so a misconfigured
base_urlcannot put the key on the wire in clear text. - Never follows redirects, which would hand the path — and the key in it —
to a host the server chooses. If you pass your own client through
ClientBuilder::http_client, that one is used as-is: build it with.redirect(reqwest::redirect::Policy::none()). - Caps response bodies at 8 MiB while streaming, so a reply with no declared length cannot exhaust memory.
- Refuses a phone number that is really a list. Kavenegar separates
recipients with commas, so an unchecked
"0912…,0913…"from a sign-up form would turn one OTP into many paid sends (SMS pumping). Every number must be plain digits. - Keeps secrets out of
Debug: the API key, a sub-account's key, and the token values of a lookup (your one-time passwords). - Validates the API key's characters, so a stray newline or
/cannot silently send the request to a different URL.
Each of these is covered by a test in tests/security.rs.
One thing to know when logging: Display on Error is safe, but Debug
includes response bodies, which routinely contain recipient phone numbers and
may contain message text. Prefer error!("{e}") over error!("{e:?}") in
production, or treat those logs as personal data.
The full policy, threat model, and reporting address are in SECURITY.md.
- Timestamps are Unix seconds, exactly as the API sends them. Convert with
chrono,jiff, or anything else if you want calendar types; this crate adds no date dependency.client.utils().server_time()reads Kavenegar's own clock. - Costs are in Rials.
- Reading the inbox marks messages read. Both
sms().receive()andsms().inbox_paged()mark what they return as read, so asking for unread messages twice will not return the same ones. Store them before you process them. select,select_outboxandlatest_outboxneed an IP allowlist entry in your panel, or they fail withApiStatus::AccessDenied.- Trial accounts can only send to their own owner's number.
- A new account must finish identity verification (احراز هویت) in the
panel. Until it does, every endpoint returns
ApiStatus::AccountNotVerified, including free ones likeserver_time. - Lookup tokens have rules. Each is at most 100 characters and may not
contain a newline or an underscore.
token,token2andtoken3may not contain spaces;token10allows 5 andtoken20allows 8. Kavenegar answers a broken rule with error 431, so this crate rejects it before sending. - Every phone and line number is checked. Only ASCII digits with an
optional leading
+are accepted (09121234567,+989121234567,00989121234567). Kavenegar takes lists as comma-separated text, so without this a number typed by an end user, like"0912…,0913…", would quietly become several recipients billed to you. Convert Persian digits (۰۹۱۲) before passing them in. - Retrying a send can send twice. After a timeout the message may already
be on its way;
is_retryable()cannot know. Attachlocal_idsbefore retrying asend, so Kavenegar drops the duplicate, and issue a fresh code rather than resending an OTP. - Local ids are numbers. Kavenegar documents them as integers, so
local_idstakesi64. A repeated local id is not sent twice.
This project is released under the MIT License.
This is an unofficial, open-source client and has no official affiliation with Kavenegar.
Maintained by Goudarz Jafari — hi@goudarzjafari.com. Source and issues: https://github.com/goudarz/kavenegar-rs.