Skip to main content

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}