ibridge_server/mail_api.rs
1// SPDX-License-Identifier: Apache-2.0
2
3//! Mail operations the tools call. The binary adapts `MailSession` to this.
4
5use ibridge_core::{
6 Attachment, CoreError, Draft, FlagChange, MailSearch, Mailbox, MailboxPath, MailboxRole,
7 Message, MessageId, MessageSummary,
8};
9
10/// One page of search hits, plus how many messages were skipped.
11#[derive(Debug, Clone, PartialEq, Eq)]
12pub struct MailHitPage {
13 /// Hits, newest first.
14 pub messages: Vec<MessageSummary>,
15 /// Present when another page exists.
16 pub next_cursor: Option<String>,
17 /// Messages skipped because they did not parse.
18 pub warnings: u32,
19}
20
21/// A message body window.
22#[derive(Debug, Clone, PartialEq, Eq)]
23pub struct MailBody {
24 /// Headers, the body window, and the attachment list.
25 pub message: Message,
26 /// Set when another window starts at this scalar offset.
27 pub next_offset: Option<usize>,
28}
29
30/// One attachment window.
31#[derive(Debug, Clone, PartialEq, Eq)]
32pub struct MailPart {
33 /// The part that was fetched.
34 pub attachment: Attachment,
35 /// Set when a text part has another window at this scalar offset.
36 pub next_offset: Option<usize>,
37}
38
39/// A message SMTP accepted.
40#[derive(Debug, Clone, PartialEq, Eq)]
41pub struct SentMail {
42 /// Id of the copy in Sent Messages.
43 ///
44 /// `None` when the message was delivered and the Sent append failed.
45 pub id: Option<MessageId>,
46}
47
48/// Where a move puts a message.
49#[derive(Debug, Clone, PartialEq, Eq)]
50#[non_exhaustive]
51pub enum MailDest {
52 /// A mailbox path.
53 Path(MailboxPath),
54 /// A well-known role.
55 Role(MailboxRole),
56}
57
58/// Mail backend for one account.
59#[trait_variant::make(Send)]
60pub trait MailApi {
61 /// Lists mailboxes.
62 ///
63 /// # Errors
64 ///
65 /// Returns [`CoreError`] when the mailbox list cannot be read.
66 async fn list_mailboxes(&self) -> Result<Vec<Mailbox>, CoreError>;
67
68 /// Searches messages.
69 ///
70 /// # Errors
71 ///
72 /// Returns [`CoreError`] when the search cannot be run.
73 async fn search(&self, query: &MailSearch) -> Result<MailHitPage, CoreError>;
74
75 /// Fetches one message. `offset` is a Unicode scalar index into the body.
76 ///
77 /// # Errors
78 ///
79 /// Returns [`CoreError`] when the message cannot be read.
80 async fn get_message(&self, id: &MessageId, offset: usize) -> Result<MailBody, CoreError>;
81
82 /// Fetches one attachment. `offset` is a Unicode scalar index into a text part.
83 ///
84 /// # Errors
85 ///
86 /// Returns [`CoreError`] when the part cannot be read.
87 async fn get_attachment(
88 &self,
89 id: &MessageId,
90 part: &str,
91 offset: usize,
92 ) -> Result<MailPart, CoreError>;
93
94 /// Fetches every decoded byte of one attachment, for saving to disk.
95 ///
96 /// A backend that cannot do this keeps the default, which refuses.
97 ///
98 /// # Errors
99 ///
100 /// Returns [`CoreError`] when the part cannot be read.
101 async fn get_attachment_bytes(
102 &self,
103 _id: &MessageId,
104 _part: &str,
105 ) -> Result<Attachment, CoreError> {
106 async { Err(CoreError::Unsupported("saving attachments")) }
107 }
108
109 /// Appends a draft.
110 ///
111 /// # Errors
112 ///
113 /// Returns [`CoreError`] when the draft cannot be saved.
114 async fn create_draft(&self, draft: &Draft) -> Result<MessageId, CoreError>;
115
116 /// Sends a message. `id: None` means SMTP accepted it and the Sent copy failed.
117 ///
118 /// # Errors
119 ///
120 /// Returns [`CoreError`] when the message cannot be sent.
121 async fn send(&self, draft: &Draft) -> Result<SentMail, CoreError>;
122
123 /// Moves a message.
124 ///
125 /// # Errors
126 ///
127 /// Returns [`CoreError`] when the move cannot be done.
128 async fn move_message(&self, id: &MessageId, destination: &MailDest) -> Result<(), CoreError>;
129
130 /// Sets or clears flags.
131 ///
132 /// # Errors
133 ///
134 /// Returns [`CoreError`] when the flags cannot be stored.
135 async fn set_flags(&self, id: &MessageId, flags: &FlagChange) -> Result<(), CoreError>;
136}