infobip_sms/lib.rs
1//! Async Rust SDK for the [Infobip SMS API].
2//!
3//! This crate wraps the latest revision of every Infobip SMS endpoint into
4//! strongly-typed Rust structs and async methods on a single [`Client`].
5//! Requests and responses are JSON; XML responses are not supported.
6//!
7//! [Infobip SMS API]: https://www.infobip.com/docs/api/channels/sms
8//!
9//! # Quick start
10//!
11//! ```no_run
12//! use infobip_sms::{Auth, Client};
13//! use infobip_sms::models::send::{
14//! SmsMessage, SmsMessageContent, SmsRequest, SmsTextMessageContent, SmsToDestination,
15//! };
16//!
17//! # async fn run() -> Result<(), infobip_sms::Error> {
18//! // Your account base URL is shown in the Infobip portal — usually
19//! // something like `https://xxxxx.api.infobip.com`.
20//! let client = Client::builder()
21//! .base_url("https://xxxxx.api.infobip.com")
22//! .auth(Auth::api_key("YOUR_API_KEY"))
23//! .build()?;
24//!
25//! let request = SmsRequest {
26//! messages: vec![SmsMessage {
27//! sender: Some("InfoSMS".into()),
28//! destinations: vec![SmsToDestination {
29//! to: "41793026727".into(),
30//! ..Default::default()
31//! }],
32//! content: SmsMessageContent::Text(SmsTextMessageContent {
33//! text: "Hello from Rust!".into(),
34//! ..Default::default()
35//! }),
36//! ..Default::default()
37//! }],
38//! options: None,
39//! };
40//!
41//! let response = client.send_messages(&request).await?;
42//! println!("Bulk ID: {:?}", response.bulk_id);
43//! # Ok(())
44//! # }
45//! ```
46//!
47//! # Endpoints
48//!
49//! Only the **latest** version of every endpoint is exposed. Deprecated v1
50//! and v2 send / log / report endpoints are intentionally omitted.
51//!
52//! | Method | Path | Client method |
53//! |---|---|---|
54//! | `POST` | `/sms/3/messages` | [`Client::send_messages`] |
55//! | `POST` | `/sms/1/preview` | [`Client::preview_message`] |
56//! | `GET` | `/sms/3/reports` | [`Client::get_delivery_reports`] |
57//! | `GET` | `/sms/3/logs` | [`Client::get_logs`] |
58//! | `GET` | `/sms/1/inbox/reports` | [`Client::get_inbound_messages`] |
59//! | `GET` | `/sms/1/bulks` | [`Client::get_scheduled_bulk`] |
60//! | `PUT` | `/sms/1/bulks` | [`Client::reschedule_bulk`] |
61//! | `GET` | `/sms/1/bulks/status` | [`Client::get_bulk_status`] |
62//! | `PUT` | `/sms/1/bulks/status` | [`Client::update_bulk_status`] |
63//! | `POST` | `/ct/1/log/end/{messageId}` | [`Client::end_conversion_log`] |
64//!
65//! # Authentication
66//!
67//! Every Infobip endpoint accepts four authentication schemes. Pick one
68//! that matches what your account is provisioned for:
69//!
70//! ```no_run
71//! use infobip_sms::Auth;
72//!
73//! // `Authorization: App <key>` — recommended for service-to-service.
74//! let _ = Auth::api_key("YOUR_API_KEY");
75//!
76//! // HTTP Basic auth.
77//! let _ = Auth::basic("username", "password");
78//!
79//! // `Authorization: IBSSO <token>` — Infobip Single Sign-On.
80//! let _ = Auth::ibsso("YOUR_IBSSO_TOKEN");
81//!
82//! // `Authorization: Bearer <token>` — OAuth2 client credentials.
83//! let _ = Auth::bearer("YOUR_OAUTH2_TOKEN");
84//! ```
85//!
86//! See [`Auth`] for details.
87//!
88//! # Error handling
89//!
90//! Every fallible call returns [`Result<T, Error>`](Error). The two main
91//! error variants you care about are:
92//!
93//! - [`Error::Api`] — emitted by the v3 endpoints (`/sms/3/*`). Wraps a
94//! structured [`ApiError`] with `errorCode`, `description`, `action`,
95//! and a list of validation violations.
96//! - [`Error::Exception`] — emitted by the legacy `/sms/1/*` endpoints.
97//! Wraps an [`ApiException`] with a `messageId` / `text` pair.
98//!
99//! Inspect the HTTP status via the `status` field on either variant. See
100//! the [`error`] module for the full type tree.
101//!
102//! # Models and webhooks
103//!
104//! All wire schemas live in [`models`]. The [`models::webhooks`] module
105//! exposes the payload shapes Infobip POSTs to your callback URLs — use
106//! them as `Deserialize` targets in your webhook handlers.
107//!
108//! # Building blocks
109//!
110//! - [`Client`] — async, cheaply cloneable wrapper around a
111//! [`reqwest::Client`].
112//! - [`ClientBuilder`] — configure base URL, auth, timeout, user-agent,
113//! or supply a custom `reqwest::Client`.
114//! - [`Auth`] — authentication scheme.
115//!
116//! # Cargo features
117//!
118//! No optional features are exposed in this version. The default feature
119//! set links `reqwest` with `rustls-tls`; if you need `native-tls`
120//! instead, build a `reqwest::Client` yourself and hand it to
121//! [`ClientBuilder::http_client`].
122//!
123//! # MSRV
124//!
125//! Edition 2024. The crate tracks the latest stable Rust release.
126
127#![warn(missing_docs)]
128#![warn(rustdoc::broken_intra_doc_links)]
129#![cfg_attr(docsrs, feature(doc_cfg))]
130
131pub mod client;
132pub mod error;
133pub mod models;
134
135mod api;
136
137pub use client::{Auth, Client, ClientBuilder};
138pub use error::{ApiError, ApiException, Error};