mailgun_sdk/endpoints/
get_events.rs

1//! Request and response module for fetching events for a domain.
2//!
3//! ### Example
4//!
5//! ```no_run
6//! # use mailgun_sdk::{
7//! #     Client,
8//! #     ParamList,
9//! #     get_events::{GetEventsParam, GetEventsParamList},
10//! # };
11//! # let client = Client::new("", "");
12//! let request = GetEventsParamList::default()
13//!     .add(GetEventsParam::Limit(1));
14//!
15//! let events = client.get_events(request).unwrap();
16//! ```
17//!
18//! [API Documentation](https://documentation.mailgun.com/en/latest/api-events.html#events)
19
20use crate::{Paging, Param, ParamError, ParamList};
21
22//- Request
23
24/// A parameter for fetching events for a domain.
25#[derive(Debug)]
26pub enum GetEventsParam<'a> {
27    /// Pretty print the result JSON.
28    Pretty(bool),
29    /// The beginning of the search time range.
30    Begin(&'a str),
31    /// The end of the search time range.
32    End(&'a str),
33    /// Defines the direction of the search time range and must be provided if
34    /// the range end time is not specified.
35    Ascending(bool),
36    /// Number of entries to return (300 max).
37    Limit(usize),
38    /// An event type.
39    Event(&'a str),
40    /// The email address of a mailing list the message was originally sent to.
41    List(&'a str),
42    /// A name of an attached file.
43    Attachment(&'a str),
44    /// An email address mentioned in the from MIME header.
45    From(&'a str),
46    /// A Mailgun message id returned by the messages API.
47    MessageId(&'a str),
48    /// A subject line.
49    Subject(&'a str),
50    /// An email address mentioned in the to MIME header.
51    To(&'a str),
52    /// Message size.
53    Size(&'a str),
54    /// An email address of a particular recipient. While messages are
55    /// addressable to one or more recipients, each event (with one exception)
56    /// tracks one recipient.
57    Recipient(&'a str),
58    /// Specific to stored events, this field tracks all of the potential
59    /// message recipients.
60    Recipients(&'a str),
61    /// User defined tags.
62    Tags(&'a str),
63    /// Temporary or Permanent. Used to filter events based on severity, if
64    /// exists (Currently failed events only).
65    Severity(&'a str),
66}
67
68impl<'a> Param for GetEventsParam<'a> {
69    fn try_as_tuple(&self) -> Result<(String, String), ParamError> {
70        Ok(match self {
71            Self::Pretty(v) => ("pretty".to_string(), v.to_string()),
72            Self::Begin(v) => ("begin".to_string(), v.to_string()),
73            Self::End(v) => ("end".to_string(), v.to_string()),
74            Self::Ascending(v) => ("ascending".to_string(), if *v { "yes".to_string() } else { "no".to_string() }),
75            Self::Limit(v) => ("limit".to_string(), v.to_string()),
76            Self::Event(v) => ("event".to_string(), v.to_string()),
77            Self::List(v) => ("list".to_string(), v.to_string()),
78            Self::Attachment(v) => ("attachment".to_string(), v.to_string()),
79            Self::From(v) => ("from".to_string(), v.to_string()),
80            Self::MessageId(v) => ("message_id".to_string(), v.to_string()),
81            Self::Subject(v) => ("subject".to_string(), v.to_string()),
82            Self::To(v) => ("to".to_string(), v.to_string()),
83            Self::Size(v) => ("size".to_string(), v.to_string()),
84            Self::Recipient(v) => ("recipient".to_string(), v.to_string()),
85            Self::Recipients(v) => ("recipients".to_string(), v.to_string()),
86            Self::Tags(v) => ("tags".to_string(), v.to_string()),
87            Self::Severity(v) => ("severity".to_string(), v.to_string()),
88        })
89    }
90}
91
92/// List of parameters for fetching events for a domain.
93#[derive(Debug)]
94pub struct GetEventsParamList<'a> {
95    pub values: Vec<GetEventsParam<'a>>,
96}
97
98impl<'a> Default for GetEventsParamList<'a> {
99    fn default() -> Self {
100        Self {
101            values: vec![
102                GetEventsParam::Pretty(false),
103            ],
104        }
105    }
106}
107
108impl<'a> ParamList for GetEventsParamList<'a> {
109    type ParamType = GetEventsParam<'a>;
110
111    fn add(mut self, param: Self::ParamType) -> Self {
112        self.values.push(param);
113
114        self
115    }
116}
117
118//- Response
119
120/// Response returned by get events endpoint.
121#[derive(Debug, Deserialize, Serialize)]
122pub struct GetEventsResponse {
123    pub items: Vec<EventItem>,
124    pub paging: Paging,
125}
126
127/// A single item found in [`GetEventsResponse`](struct.GetEventsResponse.html).
128#[derive(Debug, Deserialize, Serialize)]
129#[serde(rename_all = "kebab-case")]
130pub struct EventItem {
131    pub event: String,
132    pub id: String,
133    pub timestamp: f64,
134    pub log_level: Option<String>,
135    pub method: Option<String>,
136    pub severity: Option<String>,
137    pub envelope: Option<EventEnvelope>,
138    pub flags: Option<EventFlags>,
139    pub reject: Option<EventReject>,
140    pub delivery_status: Option<EventDeliveryStatus>,
141    pub message: EventMessage,
142    pub storage: Option<EventStorage>,
143    pub recipient: String,
144    pub recipient_domain: Option<String>,
145    pub geolocation: Option<EventGeolocation>,
146    // TODO: Figure out what the `campaigns` field looks like.
147    pub tags: Option<Vec<String>>,
148    pub ip: Option<String>,
149    pub client_info: Option<EventClientInfo>,
150    // TODO: Figure out what the `user-variables` field looks like.
151}
152
153/// A single envelope item found in [`EventItem`](struct.EventItem.html).
154#[derive(Debug, Deserialize, Serialize)]
155pub struct EventEnvelope {
156    pub targets: String,
157    pub transport: String,
158    pub sender: String,
159}
160
161/// A single event flag item found in [`EventItem`](struct.EventItem.html).
162#[derive(Debug, Deserialize, Serialize)]
163#[serde(rename_all = "kebab-case")]
164pub struct EventFlags {
165    pub is_authenticated: Option<bool>,
166    pub is_delayed_bounce: Option<bool>,
167    pub is_routed: Option<bool>,
168    pub is_system_test: Option<bool>,
169    pub is_test_mode: Option<bool>,
170}
171
172/// A single event reject item found in [`EventItem`](struct.EventItem.html).
173#[derive(Debug, Deserialize, Serialize)]
174pub struct EventReject {
175    pub reason: Option<String>,
176    pub description: Option<String>,
177}
178
179/// A single event delivery status item found in [`EventItem`](struct.EventItem.html).
180#[derive(Debug, Deserialize, Serialize)]
181#[serde(rename_all = "kebab-case")]
182pub struct EventDeliveryStatus {
183    pub tls: Option<bool>,
184    pub mx_host: Option<String>,
185    pub code: Option<i64>,
186    pub description: Option<String>,
187    pub session_seconds: Option<f64>,
188    pub utf8: Option<bool>,
189    pub attempt_no: Option<usize>,
190    pub message: Option<String>,
191    pub certificate_verified: Option<bool>,
192}
193
194/// A single event message item found in [`EventItem`](struct.EventItem.html).
195#[derive(Debug, Deserialize, Serialize)]
196pub struct EventMessage {
197    pub headers: Option<EventMessageHeader>,
198    pub attachments: Option<Vec<EventMessageAttachment>>,
199    pub recipients: Option<Vec<String>>,
200    pub size: Option<i64>,
201}
202
203/// A single event message header item found in [`EventMessage`](struct.EventMessage.html).
204#[derive(Debug, Deserialize, Serialize)]
205#[serde(rename_all = "kebab-case")]
206pub struct EventMessageHeader {
207    pub to: Option<String>,
208    pub message_id: Option<String>,
209    pub from: Option<String>,
210    pub subject: Option<String>,
211}
212
213/// A single event message attachment item found in [`EventMessage`](struct.EventMessage.html).
214#[derive(Debug, Deserialize, Serialize)]
215#[serde(rename_all = "kebab-case")]
216pub struct EventMessageAttachment {
217    pub size: Option<i64>,
218    pub content_type: Option<String>,
219    pub filename: Option<String>,
220}
221
222/// A single event storage item found in [`EventItem`](struct.EventItem.html).
223#[derive(Debug, Deserialize, Serialize)]
224pub struct EventStorage {
225    pub url: String,
226    pub key: String,
227}
228
229/// A single event geolocation item found in [`EventItem`](struct.EventItem.html).
230#[derive(Debug, Deserialize, Serialize)]
231pub struct EventGeolocation {
232    pub country: String,
233    pub region: String,
234    pub city: String,
235}
236
237/// A single event client info item found in [`EventItem`](struct.EventItem.html).
238#[derive(Debug, Deserialize, Serialize)]
239#[serde(rename_all = "kebab-case")]
240pub struct EventClientInfo {
241    pub client_type: Option<String>,
242    pub client_os: Option<String>,
243    pub device_type: Option<String>,
244    pub client_name: Option<String>,
245    pub user_agent: Option<String>,
246}
mailgun_sdk/endpoints/get_events.rs

mailgun_sdk/endpoints/
get_events.rs
