Masked email: Fastmail's Masked Email API, MaskedEmail/get and /set (ME-1, ME-7a, ME-16)

Advertised as https://www.fastmail.com/dev/maskedemail in the session and on
every account that may hold masks. Masks created through it start pending
unless the create sets a state; pending can't be set again once left; state
and the other mutable fields map onto the same records the x: API uses.

crates/jmap-proto/src/object/fastmail_masked_email.rs

@@ -0,0 +1,190 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Coffey Labs
+ *
+ * SPDX-License-Identifier: AGPL-3.0-only
+ */
+
+//! Fastmail's published Masked Email API, `MaskedEmail/get` and
+//! `MaskedEmail/set` under `https://www.fastmail.com/dev/maskedemail`
+//! (masked-email spec, "The two APIs"). The ids are the same as
+//! `x:MaskedEmail`'s, so an id is one mask whichever API reads it.
+
+use crate::{
+    object::{AnyId, JmapObject, JmapObjectId},
+    types::date::UTCDate,
+};
+use jmap_tools::{Element, Key, Property};
+use std::{borrow::Cow, str::FromStr};
+use types::id::Id;
+
+#[derive(Debug, Clone, Default)]
+pub struct FastmailMaskedEmail;
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum FastmailMaskedEmailProperty {
+    Id,
+    Email,
+    State,
+    ForDomain,
+    Description,
+    LastMessageAt,
+    CreatedAt,
+    CreatedBy,
+    Url,
+    EmailPrefix,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub enum FastmailMaskedEmailValue {
+    Id(Id),
+    Date(UTCDate),
+}
+
+impl Property for FastmailMaskedEmailProperty {
+    fn try_parse(_: Option<&Key<'_, Self>>, value: &str) -> Option<Self> {
+        FastmailMaskedEmailProperty::parse(value)
+    }
+
+    fn to_cow(&self) -> Cow<'static, str> {
+        match self {
+            FastmailMaskedEmailProperty::Id => "id",
+            FastmailMaskedEmailProperty::Email => "email",
+            FastmailMaskedEmailProperty::State => "state",
+            FastmailMaskedEmailProperty::ForDomain => "forDomain",
+            FastmailMaskedEmailProperty::Description => "description",
+            FastmailMaskedEmailProperty::LastMessageAt => "lastMessageAt",
+            FastmailMaskedEmailProperty::CreatedAt => "createdAt",
+            FastmailMaskedEmailProperty::CreatedBy => "createdBy",
+            FastmailMaskedEmailProperty::Url => "url",
+            FastmailMaskedEmailProperty::EmailPrefix => "emailPrefix",
+        }
+        .into()
+    }
+}
+
+impl FastmailMaskedEmailProperty {
+    fn parse(value: &str) -> Option<Self> {
+        hashify::tiny_map!(value.as_bytes(),
+            b"id" => FastmailMaskedEmailProperty::Id,
+            b"email" => FastmailMaskedEmailProperty::Email,
+            b"state" => FastmailMaskedEmailProperty::State,
+            b"forDomain" => FastmailMaskedEmailProperty::ForDomain,
+            b"description" => FastmailMaskedEmailProperty::Description,
+            b"lastMessageAt" => FastmailMaskedEmailProperty::LastMessageAt,
+            b"createdAt" => FastmailMaskedEmailProperty::CreatedAt,
+            b"createdBy" => FastmailMaskedEmailProperty::CreatedBy,
+            b"url" => FastmailMaskedEmailProperty::Url,
+            b"emailPrefix" => FastmailMaskedEmailProperty::EmailPrefix,
+        )
+    }
+}
+
+impl FromStr for FastmailMaskedEmailProperty {
+    type Err = ();
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        FastmailMaskedEmailProperty::parse(s).ok_or(())
+    }
+}
+
+impl Element for FastmailMaskedEmailValue {
+    type Property = FastmailMaskedEmailProperty;
+
+    fn try_parse<P>(key: &Key<'_, Self::Property>, value: &str) -> Option<Self> {
+        match key {
+            Key::Property(FastmailMaskedEmailProperty::Id) => {
+                Id::from_str(value).ok().map(FastmailMaskedEmailValue::Id)
+            }
+            Key::Property(
+                FastmailMaskedEmailProperty::CreatedAt | FastmailMaskedEmailProperty::LastMessageAt,
+            ) => UTCDate::from_str(value)
+                .ok()
+                .map(FastmailMaskedEmailValue::Date),
+            _ => None,
+        }
+    }
+
+    fn to_cow(&self) -> Cow<'static, str> {
+        match self {
+            FastmailMaskedEmailValue::Id(id) => id.to_string().into(),
+            FastmailMaskedEmailValue::Date(date) => date.to_string().into(),
+        }
+    }
+}
+
+impl JmapObject for FastmailMaskedEmail {
+    type Property = FastmailMaskedEmailProperty;
+
+    type Element = FastmailMaskedEmailValue;
+
+    type Id = Id;
+
+    type Filter = ();
+
+    type Comparator = ();
+
+    type GetArguments = ();
+
+    type SetArguments<'de> = ();
+
+    type QueryArguments = ();
+
+    type CopyArguments = ();
+
+    type ParseArguments = ();
+
+    const ID_PROPERTY: Self::Property = FastmailMaskedEmailProperty::Id;
+}
+
+impl From<Id> for FastmailMaskedEmailValue {
+    fn from(id: Id) -> Self {
+        FastmailMaskedEmailValue::Id(id)
+    }
+}
+
+impl JmapObjectId for FastmailMaskedEmailValue {
+    fn as_id(&self) -> Option<Id> {
+        match self {
+            FastmailMaskedEmailValue::Id(id) => Some(*id),
+            _ => None,
+        }
+    }
+
+    fn as_any_id(&self) -> Option<AnyId> {
+        match self {
+            FastmailMaskedEmailValue::Id(id) => Some(AnyId::Id(*id)),
+            _ => None,
+        }
+    }
+
+    fn as_id_ref(&self) -> Option<&str> {
+        None
+    }
+
+    fn try_set_id(&mut self, new_id: AnyId) -> bool {
+        if let AnyId::Id(id) = new_id {
+            *self = FastmailMaskedEmailValue::Id(id);
+            true
+        } else {
+            false
+        }
+    }
+}
+
+impl JmapObjectId for FastmailMaskedEmailProperty {
+    fn as_id(&self) -> Option<Id> {
+        None
+    }
+
+    fn as_any_id(&self) -> Option<AnyId> {
+        None
+    }
+
+    fn as_id_ref(&self) -> Option<&str> {
+        None
+    }
+
+    fn try_set_id(&mut self, _: AnyId) -> bool {
+        false
+    }
+}

crates/jmap-proto/src/object/mod.rs

@@ -18,6 +18,7 @@ pub mod calendar_event_notification;
 pub mod contact;
 pub mod email;
 pub mod email_submission;
+pub mod fastmail_masked_email; // inbuxa: masked email
 pub mod file_node;
 pub mod identity;
 pub mod mailbox;

crates/jmap-proto/src/references/eval.rs

@@ -50,6 +50,9 @@ impl Response<'_> {
                         GetResponseMethod::VacationResponse(response) => {
                             response.eval_jptr(path, &mut results)
                         }
+                        GetResponseMethod::MaskedEmail(response) => {
+                            response.eval_jptr(path, &mut results)
+                        }
                         GetResponseMethod::Principal(response) => {
                             response.eval_jptr(path, &mut results)
                         }

crates/jmap-proto/src/references/resolve.rs

@@ -41,6 +41,7 @@ impl Response<'_> {
                 GetRequestMethod::PushSubscription(request) => request.resolve_references(self)?,
                 GetRequestMethod::Sieve(request) => request.resolve_references(self)?,
                 GetRequestMethod::VacationResponse(request) => request.resolve_references(self)?,
+                GetRequestMethod::MaskedEmail(request) => request.resolve_references(self)?,
                 GetRequestMethod::Principal(request) => request.resolve_references(self)?,
                 GetRequestMethod::Quota(request) => request.resolve_references(self)?,
                 GetRequestMethod::Blob(request) => request.resolve_references(self)?,
@@ -75,6 +76,9 @@ impl Response<'_> {
                 SetRequestMethod::VacationResponse(request) => {
                     request.resolve_references(self, 1, false)?
                 }
+                SetRequestMethod::MaskedEmail(request) => {
+                    request.resolve_references(self, 1, false)?
+                }
                 SetRequestMethod::AddressBook(request) => {
                     request.resolve_references(self, 1, false)?
                 }

crates/jmap-proto/src/request/capability.rs

@@ -98,6 +98,9 @@ pub enum Capability {
     // inbuxa: the fork's own capability (contract C-1, multi-tenancy MT-22)
     #[serde(rename(serialize = "urn:inbuxa:jmap"))]
     Inbuxa = 1 << 20,
+    // inbuxa: Fastmail's Masked Email API (masked email)
+    #[serde(rename(serialize = "https://www.fastmail.com/dev/maskedemail"))]
+    FastmailMaskedEmail = 1 << 21,
 }
 
 #[derive(Debug, Clone, Copy, Default)]
@@ -347,6 +350,7 @@ impl Capability {
             Capability::WebPushVapid => "urn:ietf:params:jmap:webpush-vapid",
             Capability::EmailPush => "urn:ietf:params:jmap:emailpush",
             Capability::Inbuxa => "urn:inbuxa:jmap",
+            Capability::FastmailMaskedEmail => "https://www.fastmail.com/dev/maskedemail",
         }
     }
 
@@ -494,6 +498,7 @@ impl Capability {
             "urn:ietf:params:jmap:webpush-vapid" => Capability::WebPushVapid,
             "urn:ietf:params:jmap:emailpush" => Capability::EmailPush,
             "urn:inbuxa:jmap" => Capability::Inbuxa,
+            "https://www.fastmail.com/dev/maskedemail" => Capability::FastmailMaskedEmail,
         )
     }
 }

crates/jmap-proto/src/request/method.rs

@@ -41,6 +41,8 @@ pub enum MethodObject {
     ParticipantIdentity,
     ShareNotification,
     Registry(ObjectType),
+    // inbuxa: Fastmail's MaskedEmail
+    MaskedEmail,
 }
 
 impl MethodObject {
@@ -64,6 +66,7 @@ impl MethodObject {
             MethodObject::AddressBook | MethodObject::ContactCard => Capability::Contacts,
             MethodObject::FileNode => Capability::FileNode,
             MethodObject::Registry(_) => Capability::Stalwart,
+            MethodObject::MaskedEmail => Capability::FastmailMaskedEmail,
         }
     }
 }
@@ -235,6 +238,8 @@ impl MethodName {
             (MethodFunction::Set, MethodObject::ParticipantIdentity) => "ParticipantIdentity/set",
 
             (MethodFunction::Echo, MethodObject::Core) => "Core/echo",
+            (MethodFunction::Get, MethodObject::MaskedEmail) => "MaskedEmail/get",
+            (MethodFunction::Set, MethodObject::MaskedEmail) => "MaskedEmail/set",
             (method, MethodObject::Registry(obj)) => {
                 return Cow::Owned(format!("x:{}/{}", obj.as_str(), method.as_str()));
             }
@@ -354,6 +359,9 @@ impl MethodName {
 
             "Core/echo" => (MethodObject::Core, MethodFunction::Echo),
 
+            "MaskedEmail/get" => (MethodObject::MaskedEmail, MethodFunction::Get),
+            "MaskedEmail/set" => (MethodObject::MaskedEmail, MethodFunction::Set),
+
         ).or_else(|| {
             let (obj, fnc) = s.strip_prefix("x:")?.split_once('/')?;
             let obj = ObjectType::parse(obj)?;
@@ -401,6 +409,7 @@ impl Display for MethodObject {
             MethodObject::CalendarEvent => "CalendarEvent",
             MethodObject::CalendarEventNotification => "CalendarEventNotification",
             MethodObject::ShareNotification => "ShareNotification",
+            MethodObject::MaskedEmail => "MaskedEmail",
             MethodObject::Registry(obj) => {
                 f.write_str("x:")?;
                 return f.write_str(obj.as_str());

crates/jmap-proto/src/request/mod.rs

@@ -111,6 +111,7 @@ pub enum GetRequestMethod {
     ParticipantIdentity(Box<GetRequest<ParticipantIdentity>>),
     ShareNotification(Box<GetRequest<ShareNotification>>),
     Registry(Box<GetRequest<Registry>>),
+    MaskedEmail(Box<GetRequest<crate::object::fastmail_masked_email::FastmailMaskedEmail>>),
 }
 
 #[derive(Debug)]
@@ -131,6 +132,7 @@ pub enum SetRequestMethod<'x> {
     CalendarEventNotification(Box<SetRequest<'x, CalendarEventNotification>>),
     ParticipantIdentity(Box<SetRequest<'x, ParticipantIdentity>>),
     Registry(Box<SetRequest<'x, Registry>>),
+    MaskedEmail(Box<SetRequest<'x, crate::object::fastmail_masked_email::FastmailMaskedEmail>>),
 }
 
 #[derive(Debug)]

crates/jmap-proto/src/request/parser.rs

@@ -146,6 +146,13 @@ impl<'de> Visitor<'de> for CallVisitor {
                     return Err(de::Error::invalid_length(1, &self));
                 }
             },
+            (MethodFunction::Get, MethodObject::MaskedEmail) => match seq.next_element() {
+                Ok(Some(value)) => RequestMethod::Get(GetRequestMethod::MaskedEmail(value)),
+                Err(err) => RequestMethod::invalid(err),
+                Ok(None) => {
+                    return Err(de::Error::invalid_length(1, &self));
+                }
+            },
             (MethodFunction::Get, MethodObject::VacationResponse) => match seq.next_element() {
                 Ok(Some(value)) => RequestMethod::Get(GetRequestMethod::VacationResponse(value)),
                 Err(err) => RequestMethod::invalid(err),
@@ -290,6 +297,13 @@ impl<'de> Visitor<'de> for CallVisitor {
                     return Err(de::Error::invalid_length(1, &self));
                 }
             },
+            (MethodFunction::Set, MethodObject::MaskedEmail) => match seq.next_element() {
+                Ok(Some(value)) => RequestMethod::Set(SetRequestMethod::MaskedEmail(value)),
+                Err(err) => RequestMethod::invalid(err),
+                Ok(None) => {
+                    return Err(de::Error::invalid_length(1, &self));
+                }
+            },
             (MethodFunction::Set, MethodObject::VacationResponse) => match seq.next_element() {
                 Ok(Some(value)) => RequestMethod::Set(SetRequestMethod::VacationResponse(value)),
                 Err(err) => RequestMethod::invalid(err),

crates/jmap-proto/src/response/mod.rs

@@ -98,6 +98,7 @@ pub enum GetResponseMethod {
     ParticipantIdentity(GetResponse<ParticipantIdentity>),
     ShareNotification(GetResponse<ShareNotification>),
     Registry(GetResponse<Registry>),
+    MaskedEmail(GetResponse<crate::object::fastmail_masked_email::FastmailMaskedEmail>),
 }
 
 #[derive(Debug, serde::Serialize)]
@@ -119,6 +120,7 @@ pub enum SetResponseMethod {
     CalendarEventNotification(Box<SetResponse<CalendarEventNotification>>),
     ParticipantIdentity(Box<SetResponse<ParticipantIdentity>>),
     Registry(Box<SetResponse<Registry>>),
+    MaskedEmail(Box<SetResponse<crate::object::fastmail_masked_email::FastmailMaskedEmail>>),
 }
 
 #[derive(Debug, serde::Serialize)]
@@ -265,6 +267,19 @@ impl<'x> From<GetResponse<Sieve>> for ResponseMethod<'x> {
     }
 }
 
+// inbuxa: Fastmail's MaskedEmail
+impl<'x> From<GetResponse<crate::object::fastmail_masked_email::FastmailMaskedEmail>> for ResponseMethod<'x> {
+    fn from(value: GetResponse<crate::object::fastmail_masked_email::FastmailMaskedEmail>) -> Self {
+        ResponseMethod::Get(GetResponseMethod::MaskedEmail(value))
+    }
+}
+
+impl<'x> From<SetResponse<crate::object::fastmail_masked_email::FastmailMaskedEmail>> for ResponseMethod<'x> {
+    fn from(value: SetResponse<crate::object::fastmail_masked_email::FastmailMaskedEmail>) -> Self {
+        ResponseMethod::Set(SetResponseMethod::MaskedEmail(Box::new(value)))
+    }
+}
+
 impl<'x> From<GetResponse<VacationResponse>> for ResponseMethod<'x> {
     fn from(value: GetResponse<VacationResponse>) -> Self {
         ResponseMethod::Get(GetResponseMethod::VacationResponse(value))