paubox
Async Rust SDK for the Paubox Email API and Forms API.
Paubox is a HITRUST-certified platform for sending HIPAA-compliant email and collecting patient data through secure forms.
Installation
Add to your Cargo.toml:
[]
= "0.1"
= { = "1", = ["rt-multi-thread", "macros"] }
Feature flags
Both features are enabled by default. Disable one if you don't need it:
# Email API only
= { = "0.1", = false, = ["email"] }
# Forms API only
= { = "0.1", = false, = ["forms"] }
| Feature | Default | Description |
|---|---|---|
email |
✓ | Send HIPAA-compliant email, track delivery status |
forms |
✓ | Retrieve form definitions, submit form responses |
Quick start
Send an email
use ;
async
Check email delivery status
let disposition = client.get_email_disposition.await?;
for d in &disposition.message_deliveries
Send a message with attachments
use ;
let pdf_bytes = read?;
let attachment = from_bytes;
let msg = builder
.from
.to
.subject
.text_content
.attachment
.build?;
Retrieve a form definition
use FormsClient;
let client = new;
let form = client.get_form.await?;
println!;
Submit a form response
use ;
use json;
let client = new;
let submission = builder
.form_data
.build?;
client.submit_form.await?;
Credentials
Constructor
let client = new;
Environment variables
// Reads PAUBOX_API_KEY
let client = from_env?;
| Variable | Description |
|---|---|
PAUBOX_API_KEY |
Your Paubox API key |
Builder (with custom options)
use Duration;
let client = builder
.api_key
.timeout
.build?;
Error handling
All methods return Result<T, PauboxError>:
use PauboxError;
match client.send_message.await
Forms API note
The Forms API endpoints are public — no API key is required. They are intended to be called on behalf of form respondents. FormsClient can be created independently of PauboxClient.
If you already have a PauboxClient, you can reuse its connection pool:
let forms = client.forms; // reuses the underlying reqwest::Client
Webhooks
A webhook endpoint is a URL you own that Paubox notifies when something happens. WebhooksClient manages those subscriptions: which URL to notify, and for which events.
Unlike FormsClient, every method here needs a scoped API key, sent as Authorization: Bearer <key>:
use WebhooksClient;
let client = new;
Which events a key may subscribe to follows from its scopes. The SDK does not inspect them — the service refuses an event the key isn't scoped for with 403, and an unrecognised event with 422.
Available events
| Event | Fires when |
|---|---|
forms.submission.created |
A form submission is received |
api_mail_log_delivered |
An Email API message is delivered |
api_mail_log_opened |
A delivered message is opened |
api_mail_log_temporary_failure |
Delivery fails temporarily |
api_mail_log_permanent_failure |
Delivery fails permanently |
email.inbound.received |
Inbound mail is received |
The four Email API events keep their legacy api_mail_log_ names, so a receiver written
against the old Email API webhooks keeps working unchanged. Note these are the names on
the wire: delivered or failed on their own are rejected as unknown.
The SDK does not check these names. The catalog lives in the service, so an event added later works here without upgrading the SDK.
Subscribe a URL to an event
let created = client
.create_webhook_endpoint
.await?;
println!; // UUID
println!; // whsec_... — store this now
The endpoint itself is a flattened field, so its properties are reached through created.endpoint; signing_secret sits beside it.
signing_secret is on CreatedWebhookEndpoint and no other type, because the service returns it once and never again. There is no way to read it back: recovering from a lost secret means deleting the endpoint and creating another. Use it to verify that deliveries really came from Paubox.
List, fetch, update and delete
use ;
let list = client
.list_webhook_endpoints
.await?;
for endpoint in &list.data
println!; // total matching, not the length of data
let endpoint = client.get_webhook_endpoint.await?;
let updated = client
.update_webhook_endpoint
.await?;
client.delete_webhook_endpoint.await?;
Only the fields set on UpdateWebhookEndpoint are sent, so changing the status leaves the URL and events alone. Pausing deliveries without losing the subscription is what "disabled" is for; set "active" to resume. Setting events replaces the list rather than adding to it. Delete returns () — the service answers 204 with no body — and takes the signing secret with it.
Set page and items on ListWebhookEndpointsParams to paginate.
Webhook errors
Failures are the same PauboxError the rest of the SDK returns, with the service's {"message": "..."} promoted onto it rather than a bare status. Subscribing a target_url that already has an endpoint is a 422, and an id belonging to another account is a 404 rather than a 403 — so one account cannot probe another's for existence. An id that is not UUID-shaped is rejected as PauboxError::Validation before any request is sent.
API reference
See api.md for full documentation of all types, methods, and fields.
MSRV
Rust 1.86 or later.
License
Apache 2.0 — see LICENSE.
💬 Community & support
Questions, ideas, or want to share what you built? Join the Paubox Community — the single home for discussions across every Paubox SDK and API.
🔐 Found a security issue? Email devops@paubox.com — please don't post it publicly.