Skip to main content

loops_so/client/
transactional.rs

1use http::StatusCode;
2use serde_json::Value;
3
4use super::{LoopsClient, Page, TransactionalOptions, check};
5use crate::error::{LoopsError, Result};
6use crate::generated::{
7    CreateTransactionalEmailRequest, CreateTransactionalEmailResponse, CreateTransactionalRequest,
8    EnsureTransactionalDraftRequest, EnsureTransactionalDraftResponse,
9    GetTransactionalEmailMetricsRequest, GetTransactionalEmailMetricsResponse,
10    GetTransactionalEmailRequest, GetTransactionalEmailResponse,
11    ListPublishedTransactionalEmailsRequestQuery, ListTransactionalEmailsRequest,
12    ListTransactionalEmailsRequestQuery, ListTransactionalEmailsResponse,
13    ListTransactionalsResourceResponse, PublishTransactionalEmailRequest,
14    PublishTransactionalEmailResponse, SendTransactionalEmailRequest,
15    SendTransactionalEmailRequestHeader, SendTransactionalEmailResponse,
16    TransactionalDraftResponse, TransactionalMetricsResponse, TransactionalRequest,
17    TransactionalResource, TransactionalSuccessResponse, UpdateTransactionalEmailRequest,
18    UpdateTransactionalRequest,
19};
20use crate::responses::TransactionalEmailsResponse;
21use crate::routes::Route;
22
23impl LoopsClient {
24    /// Send a transactional email.
25    ///
26    /// An idempotency key is generated when `options` does not carry one.
27    ///
28    /// # Errors
29    ///
30    /// [`LoopsError::Api`] with status 404 when the transactional email does
31    /// not exist, 409 when the idempotency key was already used, and 400 for
32    /// other rejections such as an unpublished template.
33    pub async fn send_transactional_email(
34        &self,
35        transactional_id: &str,
36        email: &str,
37        options: TransactionalOptions,
38    ) -> Result<TransactionalSuccessResponse> {
39        const ACTION: &str = "send transactional email";
40        self.validate_email(Some(email))?;
41        let header = SendTransactionalEmailRequestHeader {
42            idempotency_key: Some(
43                options
44                    .idempotency_key
45                    .unwrap_or_else(|| uuid::Uuid::new_v4().to_string()),
46            ),
47        };
48        check(&header)?;
49        let headers = http::HeaderMap::try_from(&header)
50            .map_err(|err| LoopsError::InvalidInput(format!("Invalid idempotency key: {err}")))?;
51        let body = TransactionalRequest {
52            email: email.to_owned(),
53            transactional_id: transactional_id.to_owned(),
54            add_to_audience: options.add_to_audience,
55            data_variables: (!options.data_variables.is_empty())
56                .then_some(Value::Object(options.data_variables)),
57            attachments: (!options.attachments.is_empty()).then_some(options.attachments),
58        };
59        check(&body)?;
60        let raw = self
61            .send(Route::Transactional, &[], |r| {
62                r.headers(headers).json(&body)
63            })
64            .await?;
65        match raw.status {
66            StatusCode::NOT_FOUND => return Err(raw.failure_with("Transactional email not found")),
67            StatusCode::CONFLICT => return Err(raw.failure_with("Idempotency key conflict")),
68            _ => {}
69        }
70        match raw
71            .parse(ACTION, SendTransactionalEmailRequest::parse_response)
72            .await?
73        {
74            SendTransactionalEmailResponse::Ok(response) => Ok(response),
75            _ => Err(raw.unexpected(ACTION)),
76        }
77    }
78
79    /// List published transactional emails.
80    pub async fn list_transactional_emails(
81        &self,
82        page: Page,
83    ) -> Result<TransactionalEmailsResponse> {
84        let query = ListPublishedTransactionalEmailsRequestQuery {
85            per_page: page.per_page_param(),
86            cursor: page.cursor,
87        };
88        let raw = self
89            .send(Route::ListTransactional, &[], |r| r.query(&query))
90            .await?;
91        raw.parse_as("list transactional emails")
92    }
93
94    /// List transactional email templates, drafts included.
95    pub async fn list_transactional_templates(
96        &self,
97        page: Page,
98    ) -> Result<ListTransactionalsResourceResponse> {
99        const ACTION: &str = "list transactional templates";
100        let query = ListTransactionalEmailsRequestQuery {
101            per_page: page.per_page_param(),
102            cursor: page.cursor,
103        };
104        let raw = self
105            .send(Route::ListTransactionalTemplates, &[], |r| r.query(&query))
106            .await?;
107        match raw
108            .parse(ACTION, ListTransactionalEmailsRequest::parse_response)
109            .await?
110        {
111            ListTransactionalEmailsResponse::Ok(response) => Ok(response),
112            _ => Err(raw.unexpected(ACTION)),
113        }
114    }
115
116    /// Get a transactional email template.
117    pub async fn get_transactional_template(
118        &self,
119        transactional_id: &str,
120    ) -> Result<TransactionalResource> {
121        const ACTION: &str = "get transactional template";
122        let raw = self
123            .send(Route::GetTransactionalTemplate, &[transactional_id], |r| r)
124            .await?;
125        match raw
126            .parse(ACTION, GetTransactionalEmailRequest::parse_response)
127            .await?
128        {
129            GetTransactionalEmailResponse::Ok(template) => Ok(template),
130            _ => Err(raw.unexpected(ACTION)),
131        }
132    }
133
134    /// The names of the data variables a transactional email template
135    /// expects, for building the `data_variables` of
136    /// [`send_transactional_email`](Self::send_transactional_email). Empty for
137    /// unpublished templates.
138    pub async fn get_transactional_variables(&self, transactional_id: &str) -> Result<Vec<String>> {
139        Ok(self
140            .get_transactional_template(transactional_id)
141            .await?
142            .data_variables)
143    }
144
145    /// All-time delivery metrics of a transactional email template, totalled
146    /// across its published versions.
147    pub async fn get_transactional_template_metrics(
148        &self,
149        transactional_id: &str,
150    ) -> Result<TransactionalMetricsResponse> {
151        const ACTION: &str = "get transactional template metrics";
152        let raw = self
153            .send(
154                Route::GetTransactionalTemplateMetrics,
155                &[transactional_id],
156                |r| r,
157            )
158            .await?;
159        match raw
160            .parse(ACTION, GetTransactionalEmailMetricsRequest::parse_response)
161            .await?
162        {
163            GetTransactionalEmailMetricsResponse::Ok(metrics) => Ok(metrics),
164            _ => Err(raw.unexpected(ACTION)),
165        }
166    }
167
168    /// Create a draft transactional email template.
169    pub async fn create_transactional_template(
170        &self,
171        name: &str,
172        transactional_group_id: Option<&str>,
173    ) -> Result<TransactionalDraftResponse> {
174        const ACTION: &str = "create transactional template";
175        let body = CreateTransactionalRequest {
176            name: name.to_owned(),
177            transactional_group_id: transactional_group_id.map(str::to_owned),
178        };
179        check(&body)?;
180        let raw = self
181            .send(Route::CreateTransactionalTemplate, &[], |r| r.json(&body))
182            .await?;
183        match raw
184            .parse(ACTION, CreateTransactionalEmailRequest::parse_response)
185            .await?
186        {
187            CreateTransactionalEmailResponse::Created(draft) => Ok(draft),
188            _ => Err(raw.unexpected(ACTION)),
189        }
190    }
191
192    /// Rename a transactional email template or move it to another group.
193    pub async fn update_transactional_template(
194        &self,
195        transactional_id: &str,
196        name: Option<&str>,
197        transactional_group_id: Option<&str>,
198    ) -> Result<TransactionalResource> {
199        const ACTION: &str = "update transactional template";
200        let body = UpdateTransactionalRequest {
201            name: name.map(str::to_owned),
202            transactional_group_id: transactional_group_id.map(str::to_owned),
203        };
204        let raw = self
205            .send(
206                Route::UpdateTransactionalTemplate,
207                &[transactional_id],
208                |r| r.json(&body),
209            )
210            .await?;
211        match raw
212            .parse(ACTION, UpdateTransactionalEmailRequest::parse_response)
213            .await?
214        {
215            GetTransactionalEmailResponse::Ok(template) => Ok(template),
216            _ => Err(raw.unexpected(ACTION)),
217        }
218    }
219
220    /// Create the draft of a transactional email template, or return the
221    /// existing one.
222    pub async fn draft_transactional_template(
223        &self,
224        transactional_id: &str,
225    ) -> Result<TransactionalDraftResponse> {
226        const ACTION: &str = "draft transactional template";
227        let raw = self
228            .send(
229                Route::DraftTransactionalTemplate,
230                &[transactional_id],
231                |r| r,
232            )
233            .await?;
234        match raw
235            .parse(ACTION, EnsureTransactionalDraftRequest::parse_response)
236            .await?
237        {
238            EnsureTransactionalDraftResponse::Ok(draft) => Ok(draft),
239            _ => Err(raw.unexpected(ACTION)),
240        }
241    }
242
243    /// Publish the draft of a transactional email template.
244    pub async fn publish_transactional_template(
245        &self,
246        transactional_id: &str,
247    ) -> Result<TransactionalResource> {
248        const ACTION: &str = "publish transactional template";
249        let raw = self
250            .send(
251                Route::PublishTransactionalTemplate,
252                &[transactional_id],
253                |r| r,
254            )
255            .await?;
256        match raw
257            .parse(ACTION, PublishTransactionalEmailRequest::parse_response)
258            .await?
259        {
260            PublishTransactionalEmailResponse::Ok(template) => Ok(template),
261            _ => Err(raw.unexpected(ACTION)),
262        }
263    }
264}