Send email from Rust with one HTTP call.

use serde::{Deserialize, Serialize};
use std::time::Duration;

// serde writes the struct as camelCase JSON, which is what the API reads.
// Optional fields are skipped when None so the request validates cleanly.
#[derive(Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SendEmail<'a> {
    pub from: &'a str,
    pub to: &'a str,
    pub subject: &'a str,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub html: Option<&'a str>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub text: Option<&'a str>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub template_id: Option<&'a str>,
}

#[derive(Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
pub struct Sent {
    pub email_id: String,
}

#[derive(Deserialize, Debug)]
pub struct ApiError {
    pub code: String,
    pub message: String,
}

#[derive(Deserialize)]
struct ErrorEnvelope {
    error: ApiError,
}

#[derive(Debug)]
pub enum SendError {
    // The request never got an answer: DNS, TLS, timeout.
    Transport(reqwest::Error),
    // The API answered and refused.
    Refused { status: u16, error: ApiError },
}

pub struct Notix {
    http: reqwest::Client,
    api_key: String,
    base_url: String,
}

impl Notix {
    pub fn new(api_key: String) -> Self {
        Self {
            http: reqwest::Client::builder()
                .timeout(Duration::from_secs(10))
                .build()
                .expect("reqwest client"),
            api_key,
            // Pointing at a different Notix base URL (a staging environment, say)?
            // Change this; the default is the hosted API.
            base_url: "https://app.usenotix.dev/api/v1".to_string(),
        }
    }

    pub async fn send(&self, email: &SendEmail<'_>, idempotency_key: &str) -> Result<Sent, SendError> {
        let response = self
            .http
            .post(format!("{}/emails", self.base_url))
            .bearer_auth(&self.api_key)
            // One key per business event, so a retry can never send twice.
            .header("Idempotency-Key", idempotency_key)
            .json(email)
            .send()
            .await
            .map_err(SendError::Transport)?;

        let status = response.status();
        if status.is_success() {
            return response.json::<Sent>().await.map_err(SendError::Transport);
        }

        // Every refusal is { "error": { "code", "message" } }; a 413 for a
        // body over 20 MB is the one answer with no JSON.
        let error = match response.json::<ErrorEnvelope>().await {
            Ok(envelope) => envelope.error,
            Err(_) => ApiError { code: format!("HTTP_{}", status.as_u16()), message: "No error body".into() },
        };
        Err(SendError::Refused { status: status.as_u16(), error })
    }
}

mod notix;

use notix::{Notix, SendEmail, SendError};

#[tokio::main]
async fn main() {
    // The key comes from the environment, never from source.
    let client = Notix::new(std::env::var("NOTIX_API_KEY").expect("NOTIX_API_KEY"));

    let email = SendEmail {
        from: "receipts@acme.com",
        to: "customer@example.com",
        subject: "Your receipt for order 4471",
        html: Some("<p>Thanks for your order.</p>"),
        text: Some("Thanks for your order."),
        template_id: None,
    };

    match client.send(&email, "order-4471-receipt").await {
        Ok(sent) => println!("queued {}", sent.email_id),
        Err(SendError::Refused { status, error }) => {
            eprintln!("API said no ({status}): {} {}", error.code, error.message)
        }
        Err(SendError::Transport(e)) => eprintln!("no answer: {e}"),
    }
}

curl -X POST https://app.usenotix.dev/api/v1/emails \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Idempotency-Key: order-4471-receipt" \
  -H "Content-Type: application/json" \
  -d '{ "from": "receipts@acme.com", "to": "customer@example.com",
        "subject": "Your receipt for order 4471",
        "html": "<p>Thanks for your order.</p>", "text": "Thanks for your order." }'

# 200 { "emailId": "eml_abc123" }
# 400 { "error": { "code": "BAD_REQUEST",   "message": "..." } }   your request
# 401 { "error": { "code": "UNAUTHORIZED",  "message": "..." } }   bad or missing key
# 409 { "error": { "code": "NOT_UNIQUE",    "message": "..." } }   same key, different body
# 429 { "error": { "code": "RATE_LIMITED",  "message": "Rate limit exceeded. Try again in 60 seconds." } }