Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

fix(channels): clarify empty DMs and email nonusers immediately (#8582)

Jacob Beckerman3fe2af700bf2
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md
index d59c9b75de..aa0522884b 100644
--- a/apps/web/AGENTS.md
+++ b/apps/web/AGENTS.md
@@ -134,6 +134,8 @@ without changing the active route. Backend registration still verifies account
ownership. Cancel, logout, and the ten-minute timeout retire pending callbacks.
### General
+
+- Empty human DMs use the shared centered conversations graphic and explain email delivery to nonusers; keep this state out of agent DMs, loading/error states, and populated timelines.
- Enable persisted email/calendar review controls only for the review’s saved acting account; historical reviews fall back to the session owner. Require session edit access on desktop and mobile.
- Email draft reads compare server generations before choosing cached delivery state over a restored working copy; only a definitive first-submission rejection permits local send recovery without server cancellation.
- Compose settings pages with `features/settings/primitives.tsx` so section headings,
diff --git a/apps/web/src/features/channel/Channel/Channel.tsx b/apps/web/src/features/channel/Channel/Channel.tsx
index 5326b6bb63..e3820ce370 100644
--- a/apps/web/src/features/channel/Channel/Channel.tsx
+++ b/apps/web/src/features/channel/Channel/Channel.tsx
@@ -130,6 +130,7 @@ import {
createTargetMessageController,
type TargetMessageController,
} from './create-target-message-controller';
+import { DirectMessageEmptyState } from './DirectMessageEmptyState';
import { buildChannelMessageListMeta } from './message-list-meta';
import { ScrollToBottomOverlay } from './ScrollToBottomOverlay';
import {
@@ -760,7 +761,20 @@ export function Channel(props: ChannelProps) {
direction="desc"
/>
</Show>
- <Show when={messageIndex.entryKeys.length > 0}>
+ <Show
+ when={messageIndex.entryKeys.length > 0}
+ fallback={
+ <Show
+ when={
+ messagesQuery.isSuccess &&
+ channelType() === ChannelTypeEnum.DirectMessage &&
+ !channel()?.agent_dm
+ }
+ >
+ <DirectMessageEmptyState />
+ </Show>
+ }
+ >
<div
class="relative flex-1 min-h-0"
ref={setThreadListContainerEl}
diff --git a/apps/web/src/features/channel/Channel/DirectMessageEmptyState.tsx b/apps/web/src/features/channel/Channel/DirectMessageEmptyState.tsx
new file mode 100644
index 0000000000..817e50796d
--- /dev/null
+++ b/apps/web/src/features/channel/Channel/DirectMessageEmptyState.tsx
@@ -0,0 +1,17 @@
+import EmptyStateChannelsGraphic from '@design/empty-state-channels.svg';
+import { EmptyStatePanel } from '@ui/components/EmptyStatePanel';
+
+export function DirectMessageEmptyState() {
+ return (
+ <EmptyStatePanel
+ centered
+ graphic={EmptyStateChannelsGraphic}
+ graphicClass="size-40 sm:size-48"
+ title="Say hello"
+ description="Send a message to start the conversation. If they’re not on Macro yet, they’ll receive your message by email right away."
+ descriptionClass="max-w-sm text-balance"
+ topSpacerClass="basis-0 mobile:basis-0 grow"
+ class="min-h-0 px-6 @4xl:px-6"
+ />
+ );
+}
diff --git a/crates/channels/AGENTS.md b/crates/channels/AGENTS.md
index eaae7a913b..1829cc7671 100644
--- a/crates/channels/AGENTS.md
+++ b/crates/channels/AGENTS.md
@@ -56,6 +56,8 @@ DMs, and the shared message store other domains discuss things on.
## Gotchas
+- Human DM messages to nonusers use immediate email, including mentions and replies; empty DM creation, bot messages, and silent/mentions-only policies do not trigger this path. Keep registered recipients on their normal notification routes.
+
- DM invitation emails must stay distinguishable from channel invites (#7964) —
don't collapse the two email templates.
- Legacy document/CRM/channel message paths were removed (#6732); don't
diff --git a/crates/channels/src/domain/side_effects.rs b/crates/channels/src/domain/side_effects.rs
index 12b2d5b4b2..2074299334 100644
--- a/crates/channels/src/domain/side_effects.rs
+++ b/crates/channels/src/domain/side_effects.rs
@@ -23,6 +23,8 @@ use std::collections::HashSet;
use tracing::Instrument as _;
use uuid::Uuid;
+mod dm_email;
+
/// Parse a mention entity id in the canonical `bot|<uuid>` principal form.
fn mention_bot_id(entity_id: &str) -> Option<BotId> {
BotIdStr::parse_from_str(entity_id)
@@ -208,6 +210,8 @@ pub enum ChannelNotificationEffect {
},
/// Participants were invited to a channel.
Invite {
+ /// Stable identity for a DM email; ordinary invitations have no message key.
+ message_id: Option<Uuid>,
/// Channel receiving participants.
channel_id: Uuid,
/// User that invited the participants.
@@ -236,6 +240,7 @@ pub struct ChannelSideEffectService<C, R, N, K, B = NoopMacroEventBroker> {
}
struct InviteNotificationRequest {
+ message_id: Option<Uuid>,
channel_id: Uuid,
invited_by_user_id: MacroUserIdStr<'static>,
recipient_user_ids: Vec<MacroUserIdStr<'static>>,
@@ -507,7 +512,7 @@ where
} else {
return;
};
- let context = match self
+ let mut context = match self
.build_posted_message_context(
channel_id,
metadata,
@@ -525,6 +530,11 @@ where
}
};
+ if notification_policy == PostMessageNotificationPolicy::Default {
+ self.send_unregistered_dm_email(channel_id, &message, &mut context)
+ .await;
+ }
+
self.send_user_mention_notifications(channel_id, &message, has_attachments, &context)
.await;
self.send_document_mention_notifications(channel_id, &message, has_attachments, &context)
@@ -786,6 +796,8 @@ where
}
};
self.send_invite_notification(InviteNotificationRequest {
+ message_id: (context.metadata.channel_type == ChannelType::DirectMessage)
+ .then_some(message.id),
channel_id,
invited_by_user_id,
recipient_user_ids,
@@ -843,6 +855,7 @@ where
};
self.send_invite_notification(InviteNotificationRequest {
+ message_id: None,
channel_id,
invited_by_user_id,
recipient_user_ids,
@@ -856,6 +869,7 @@ where
async fn send_invite_notification(&self, req: InviteNotificationRequest) {
let InviteNotificationRequest {
+ message_id,
channel_id,
invited_by_user_id,
recipient_user_ids,
@@ -870,6 +884,7 @@ where
.partition(|id| existing_user_ids.contains(id.as_ref()));
self.send_notification(ChannelNotificationEffect::Invite {
+ message_id,
channel_id,
invited_by_user_id,
registered_recipient_ids,
diff --git a/crates/channels/src/domain/side_effects/dm_email.rs b/crates/channels/src/domain/side_effects/dm_email.rs
new file mode 100644
index 0000000000..7ff0730597
--- /dev/null
+++ b/crates/channels/src/domain/side_effects/dm_email.rs
@@ -0,0 +1,80 @@
+//! Immediate email delivery for human DMs to people without Macro accounts.
+
+use super::*;
+
+impl<C, R, N, K, B> ChannelSideEffectService<C, R, N, K, B>
+where
+ C: ChannelSideEffectContext + Clone,
+ R: ChannelRealtimePublisher + Clone,
+ N: ChannelNotificationSender + Clone,
+ K: ChannelContactsDispatcher + Clone,
+{
+ #[tracing::instrument(skip_all, fields(channel_id = %channel_id, message_id = %message.id))]
+ pub(super) async fn send_unregistered_dm_email(
+ &self,
+ channel_id: Uuid,
+ message: &MutatedMessage,
+ context: &mut PostedMessageNotificationContext,
+ ) {
+ if context.metadata.channel_type != ChannelType::DirectMessage {
+ return;
+ }
+ let Some(sender) = context.sender.as_user().cloned() else {
+ return;
+ };
+ let recipients = &context.recipients_without_sender;
+ let existing = match self
+ .context
+ .get_existing_user_ids(recipients.iter().cloned().collect())
+ .await
+ {
+ Ok(existing) => existing,
+ Err(err) => {
+ let err: anyhow::Error = err.into();
+ tracing::error!(error=?err, "unable to resolve DM email recipients");
+ return;
+ }
+ };
+ let unregistered: HashSet<_> = recipients
+ .iter()
+ .filter(|id| !existing.contains(id.as_ref()))
+ .cloned()
+ .collect();
+ if unregistered.is_empty() {
+ return;
+ }
+
+ let effect = ChannelNotificationEffect::Invite {
+ message_id: Some(message.id),
+ channel_id,
+ invited_by_user_id: sender,
+ registered_recipient_ids: HashSet::new(),
+ unregistered_recipient_ids: unregistered.clone(),
+ sender_profile_picture_url: context.sender_profile_picture_url.clone(),
+ message_content: Some(message.content.clone()),
+ metadata: context.metadata.clone(),
+ };
+ if let Err(err) = self.notifications.send(effect).await {
+ let err: anyhow::Error = err.into();
+ tracing::error!(error=?err, "unable to queue DM email");
+ return;
+ }
+
+ // The DM invitation template includes the message and queues a standalone
+ // email. Keep these recipients out of the normal mention/reply/first-message
+ // paths so one message cannot also send a second invitation or digest.
+ context
+ .recipients_without_sender
+ .retain(|id| !unregistered.contains(id));
+ context
+ .recipients_without_sender_and_mentions
+ .retain(|id| !unregistered.contains(id));
+ context
+ .user_mentions
+ .retain(|id| !unregistered.iter().any(|user| user.as_ref() == id));
+ context
+ .thread_context
+ .participants
+ .retain(|id| !unregistered.contains(id));
+ }
+}
diff --git a/crates/channels/src/domain/side_effects/test.rs b/crates/channels/src/domain/side_effects/test.rs
index ccb0985d0d..560d5ea239 100644
--- a/crates/channels/src/domain/side_effects/test.rs
+++ b/crates/channels/src/domain/side_effects/test.rs
@@ -14,6 +14,7 @@ use std::sync::{Arc, Mutex};
struct FakeContext {
message_count: i64,
fail_existing_user_lookup: bool,
+ unregistered_users: HashSet<String>,
document_mentions: Vec<ChannelDocumentMention>,
bot_profile: Option<BotSenderProfile>,
bot_profile_lookup_count: Arc<Mutex<usize>>,
@@ -25,6 +26,7 @@ impl Default for FakeContext {
Self {
message_count: 2,
fail_existing_user_lookup: false,
+ unregistered_users: HashSet::new(),
document_mentions: Vec::new(),
bot_profile: Some(BotSenderProfile {
name: "Test Bot".to_string(),
@@ -53,6 +55,7 @@ impl ChannelSideEffectContext for FakeContext {
Ok(user_ids
.into_iter()
.map(|user_id| user_id.as_ref().to_string())
+ .filter(|id| !self.unregistered_users.contains(id))
.collect())
}
@@ -100,6 +103,7 @@ impl ChannelRealtimePublisher for FakeRealtime {
#[derive(Clone, Default)]
struct FakeNotifications {
effects: Arc<Mutex<Vec<ChannelNotificationEffect>>>,
+ fail_next: Arc<Mutex<bool>>,
}
impl ChannelNotificationSender for FakeNotifications {
@@ -107,6 +111,9 @@ impl ChannelNotificationSender for FakeNotifications {
async fn send(&self, notification: ChannelNotificationEffect) -> Result<(), Self::Err> {
self.effects.lock().unwrap().push(notification);
+ if std::mem::take(&mut *self.fail_next.lock().unwrap()) {
+ anyhow::bail!("notification queue unavailable");
+ }
Ok(())
}
}
@@ -1300,3 +1307,217 @@ async fn handle_publishes_mention_events_alongside_channel_events() {
assert_eq!(published[0].key, "bot-1");
assert_eq!(published[0].envelope["event_type"], "mention.created");
}
+
+#[tokio::test]
+async fn nonuser_dm_messages_email_once_including_mentions_and_replies() {
+ for message_count in [1, 2] {
+ for is_reply in [false, true] {
+ for mentioned in [false, true] {
+ let channel_id = Uuid::new_v4();
+ let message_id = Uuid::new_v4();
+ let recipient = user("[email protected]");
+ let sender = user("[email protected]");
+ let notifications = FakeNotifications::default();
+ let service = ChannelSideEffectService::new(
+ FakeContext {
+ message_count,
+ unregistered_users: HashSet::from([recipient.to_string()]),
+ ..FakeContext::default()
+ },
+ FakeRealtime::default(),
+ notifications.clone(),
+ FakeContacts::default(),
+ );
+ let mut event = bot_message_posted_event(
+ channel_id,
+ message_id,
+ is_reply.then(Uuid::new_v4),
+ &[sender.as_ref(), recipient.as_ref()],
+ );
+ if let ChannelEvent::MessagePosted {
+ metadata,
+ message,
+ mentions,
+ ..
+ } = &mut event
+ {
+ metadata.channel_type = ChannelType::DirectMessage;
+ message.sender_id = Sender::new_from_user(sender.clone());
+ if mentioned {
+ mentions.push(SimpleMention::user(&recipient));
+ }
+ }
+ service.handle(event).await;
+ let effects = notifications.effects.lock().unwrap();
+ let emails: Vec<_> = effects
+ .iter()
+ .filter_map(|effect| match effect {
+ ChannelNotificationEffect::Invite {
+ message_id,
+ unregistered_recipient_ids,
+ message_content,
+ ..
+ } if !unregistered_recipient_ids.is_empty() => {
+ Some((message_id, unregistered_recipient_ids, message_content))
+ }
+ _ => None,
+ })
+ .collect();
+ assert_eq!(emails.len(), 1);
+ assert_eq!(*emails[0].0, Some(message_id));
+ assert_eq!(*emails[0].1, HashSet::from([recipient]));
+ assert_eq!(emails[0].2.as_deref(), Some("hello"));
+ }
+ }
+ }
+}
+
+#[tokio::test]
+async fn immediate_dm_email_excludes_registered_users_bots_and_silent_messages() {
+ for (registered, bot, policy, channel_type) in [
+ (
+ true,
+ false,
+ PostMessageNotificationPolicy::Default,
+ ChannelType::DirectMessage,
+ ),
+ (
+ false,
+ true,
+ PostMessageNotificationPolicy::Default,
+ ChannelType::DirectMessage,
+ ),
+ (
+ false,
+ false,
+ PostMessageNotificationPolicy::Silent,
+ ChannelType::DirectMessage,
+ ),
+ (
+ false,
+ false,
+ PostMessageNotificationPolicy::MentionsOnly,
+ ChannelType::DirectMessage,
+ ),
+ (
+ false,
+ false,
+ PostMessageNotificationPolicy::Default,
+ ChannelType::Private,
+ ),
+ ] {
+ let sender = user("[email protected]");
+ let recipient = user("[email protected]");
+ let notifications = FakeNotifications::default();
+ let service = ChannelSideEffectService::new(
+ FakeContext {
+ unregistered_users: if registered {
+ HashSet::new()
+ } else {
+ HashSet::from([recipient.to_string()])
+ },
+ ..FakeContext::default()
+ },
+ FakeRealtime::default(),
+ notifications.clone(),
+ FakeContacts::default(),
+ );
+ let mut event = bot_message_posted_event(
+ Uuid::new_v4(),
+ Uuid::new_v4(),
+ None,
+ &[sender.as_ref(), recipient.as_ref()],
+ );
+ if let ChannelEvent::MessagePosted {
+ metadata,
+ message,
+ notification_policy,
+ ..
+ } = &mut event
+ {
+ metadata.channel_type = channel_type;
+ *notification_policy = policy;
+ if !bot {
+ message.sender_id = Sender::new_from_user(sender);
+ }
+ }
+ service.handle(event).await;
+ assert!(!notifications.effects.lock().unwrap().iter().any(|effect| matches!(effect, ChannelNotificationEffect::Invite { unregistered_recipient_ids, .. } if !unregistered_recipient_ids.is_empty())));
+ }
+}
+
+#[tokio::test]
+async fn creating_empty_dm_does_not_send_email_or_notifications() {
+ let recipient = user("[email protected]");
+ let notifications = FakeNotifications::default();
+ let service = ChannelSideEffectService::new(
+ FakeContext {
+ unregistered_users: HashSet::from([recipient.to_string()]),
+ ..FakeContext::default()
+ },
+ FakeRealtime::default(),
+ notifications.clone(),
+ FakeContacts::default(),
+ );
+ service
+ .handle(ChannelEvent::ChannelCreated {
+ channel_id: Uuid::new_v4(),
+ actor: Sender::new_from_user(user("[email protected]")),
+ on_behalf_of: None,
+ channel_type: ChannelType::DirectMessage,
+ channel_name: None,
+ participant_user_ids: vec![user("[email protected]"), recipient],
+ })
+ .await;
+ assert!(notifications.effects.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn first_dm_email_fallback_preserves_message_deduplication_key() {
+ let sender = user("[email protected]");
+ let recipient = user("[email protected]");
+ let message_id = Uuid::new_v4();
+ let notifications = FakeNotifications::default();
+ *notifications.fail_next.lock().unwrap() = true;
+ let service = ChannelSideEffectService::new(
+ FakeContext {
+ message_count: 1,
+ unregistered_users: HashSet::from([recipient.to_string()]),
+ ..FakeContext::default()
+ },
+ FakeRealtime::default(),
+ notifications.clone(),
+ FakeContacts::default(),
+ );
+ let mut event = bot_message_posted_event(
+ Uuid::new_v4(),
+ message_id,
+ None,
+ &[sender.as_ref(), recipient.as_ref()],
+ );
+ if let ChannelEvent::MessagePosted {
+ metadata, message, ..
+ } = &mut event
+ {
+ metadata.channel_type = ChannelType::DirectMessage;
+ message.sender_id = Sender::new_from_user(sender);
+ }
+ service.handle(event).await;
+ let effects = notifications.effects.lock().unwrap();
+ assert_eq!(effects.len(), 2);
+ for effect in effects.iter() {
+ let ChannelNotificationEffect::Invite {
+ message_id: key,
+ unregistered_recipient_ids,
+ ..
+ } = effect
+ else {
+ panic!("expected email attempt");
+ };
+ assert_eq!(*key, Some(message_id));
+ assert_eq!(
+ *unregistered_recipient_ids,
+ HashSet::from([recipient.clone()])
+ );
+ }
+}
diff --git a/crates/channels/src/outbound/notification_sender.rs b/crates/channels/src/outbound/notification_sender.rs
index c2f964f3ba..c577b51edc 100644
--- a/crates/channels/src/outbound/notification_sender.rs
+++ b/crates/channels/src/outbound/notification_sender.rs
@@ -51,6 +51,7 @@ fn to_common_metadata(metadata: ChannelMetadata) -> CommonChannelMetadata {
}
struct InviteNotificationDelivery {
+ message_id: Option<Uuid>,
channel_id: Uuid,
invited_by_user_id: MacroUserIdStr<'static>,
registered_recipient_ids: HashSet<MacroUserIdStr<'static>>,
@@ -65,6 +66,7 @@ async fn send_invite_notifications(
delivery: InviteNotificationDelivery,
) -> anyhow::Result<()> {
let InviteNotificationDelivery {
+ message_id,
channel_id,
invited_by_user_id,
registered_recipient_ids,
@@ -74,6 +76,8 @@ async fn send_invite_notifications(
common,
} = delivery;
let notification = ChannelInviteMetadata {
+ message_id,
+ email_recipient: None,
invited_by: invited_by_user_id.clone(),
channel_name: common.channel_name,
is_direct_message: matches!(
@@ -97,18 +101,34 @@ async fn send_invite_notifications(
.with_apns()
.with_conn_gateway(),
),
- ingress.send_notification(
- SendNotificationRequestBuilder {
- notification_entity: model_entity::EntityType::Channel
- .with_entity_string(channel_id.to_string()),
- secondary_notification_entity: None,
- notification,
- sender_id: Some(invited_by_user_id.clone()),
- recipient_ids: unregistered_recipient_ids,
+ async {
+ let mut result = Ok(());
+ for recipient in unregistered_recipient_ids {
+ let mut email_notification = notification.clone();
+ if email_notification.is_direct_message && message_id.is_some() {
+ email_notification.email_recipient = Some(recipient.clone());
+ }
+ if let Err(error) = ingress
+ .send_notification(
+ SendNotificationRequestBuilder {
+ notification_entity: model_entity::EntityType::Channel
+ .with_entity_string(channel_id.to_string()),
+ secondary_notification_entity: None,
+ notification: email_notification,
+ sender_id: Some(invited_by_user_id.clone()),
+ recipient_ids: HashSet::from([recipient]),
+ }
+ .into_request()
+ .with_email(),
+ )
+ .await
+ {
+ tracing::error!(error=?error, %channel_id, "unable to queue recipient invite email");
+ result = Err(error);
+ }
}
- .into_request()
- .with_email(),
- )
+ result
+ }
)
.map_err(|e| anyhow::anyhow!("{e:?}"))?;
@@ -336,6 +356,7 @@ where
.map_err(|e| anyhow::anyhow!("{e:?}"))?;
}
ChannelNotificationEffect::Invite {
+ message_id,
channel_id,
invited_by_user_id,
registered_recipient_ids,
@@ -347,6 +368,7 @@ where
send_invite_notifications(
&*self.ingress,
InviteNotificationDelivery {
+ message_id,
channel_id,
invited_by_user_id,
registered_recipient_ids,
diff --git a/crates/channels/src/outbound/notification_sender/test.rs b/crates/channels/src/outbound/notification_sender/test.rs
index ea24699329..0496c7acde 100644
--- a/crates/channels/src/outbound/notification_sender/test.rs
+++ b/crates/channels/src/outbound/notification_sender/test.rs
@@ -1,6 +1,9 @@
use super::*;
use notification_hex::domain::{
- models::{Notification, SendNotificationRequest, request::NotificationResult},
+ models::{
+ Notification, SendNotificationRequest, queue_message::IngressQueueMessage,
+ request::NotificationResult,
+ },
service::SendNotificationError,
};
use rootcause::Report;
@@ -22,10 +25,9 @@ impl NotificationIngress for CapturingIngress {
&'a self,
req: SendNotificationRequest<'a, T, U>,
) -> Result<Option<NotificationResult<'a>>, Report<SendNotificationError>> {
- self.sent
- .lock()
- .unwrap()
- .push(serde_json::to_value(req).unwrap());
+ self.sent.lock().unwrap().push(
+ serde_json::to_value(IngressQueueMessage::from_request(&req).unwrap().request).unwrap(),
+ );
Ok(None)
}
}
@@ -53,6 +55,7 @@ async fn invite_delivery_preserves_dm_context_for_email_and_push() {
NotificationChannelSender::new(ingress.clone())
.send(ChannelNotificationEffect::Invite {
+ message_id: Some(Uuid::from_u128(2)),
channel_id,
invited_by_user_id: sender,
registered_recipient_ids: HashSet::from([registered.clone()]),
@@ -86,6 +89,18 @@ async fn invite_delivery_preserves_dm_context_for_email_and_push() {
.find(|req| !req["build_email"].is_null())
.unwrap();
assert_eq!(email["req"]["recipient_ids"], json!([unregistered]));
+ assert!(email["build_apns"].is_null());
+ assert_eq!(email["send_conn_gateway"], false);
+ assert!(
+ email["req"]["notification"]["content"]
+ .get("messageId")
+ .is_none()
+ );
+ assert!(
+ email["req"]["notification"]["content"]
+ .get("emailRecipient")
+ .is_none()
+ );
let email_content = &email["build_email"]["content"];
assert_eq!(
email_content["subject"],
@@ -121,3 +136,47 @@ async fn invite_delivery_preserves_dm_context_for_email_and_push() {
);
}
}
+
+#[tokio::test]
+async fn dm_email_delivery_keys_are_per_recipient_and_stable_on_retry() {
+ let ingress = Arc::new(CapturingIngress::default());
+ let effect = ChannelNotificationEffect::Invite {
+ channel_id: Uuid::new_v4(),
+ message_id: Some(Uuid::new_v4()),
+ invited_by_user_id: MacroUserIdStr::try_from_email("[email protected]").unwrap(),
+ registered_recipient_ids: HashSet::new(),
+ unregistered_recipient_ids: HashSet::from([
+ MacroUserIdStr::try_from_email("[email protected]").unwrap(),
+ MacroUserIdStr::try_from_email("[email protected]").unwrap(),
+ ]),
+ sender_profile_picture_url: None,
+ message_content: Some("hello".to_string()),
+ metadata: ChannelMetadata {
+ channel_type: ChannelType::DirectMessage,
+ channel_name: "Direct message".to_string(),
+ },
+ };
+ let sender = NotificationChannelSender::new(ingress.clone());
+ sender.send(effect.clone()).await.unwrap();
+ sender.send(effect).await.unwrap();
+ let sent = ingress.sent.lock().unwrap();
+ let emails: Vec<_> = sent
+ .iter()
+ .filter(|req| !req["build_email"].is_null())
+ .collect();
+ assert_eq!(emails.len(), 4);
+ assert_ne!(
+ emails[0]["build_email"]["rate_limit_key"],
+ emails[1]["build_email"]["rate_limit_key"]
+ );
+ for email in &emails[..2] {
+ let retried = emails[2..]
+ .iter()
+ .find(|retry| retry["req"]["recipient_ids"] == email["req"]["recipient_ids"])
+ .unwrap();
+ assert_eq!(
+ email["build_email"]["rate_limit_key"],
+ retried["build_email"]["rate_limit_key"]
+ );
+ }
+}
diff --git a/crates/invite_email/AGENTS.md b/crates/invite_email/AGENTS.md
index 7b3065dc3f..9c25d7e099 100644
--- a/crates/invite_email/AGENTS.md
+++ b/crates/invite_email/AGENTS.md
@@ -34,6 +34,8 @@ invites, and the colleague-joined email.
## Recipes
+- DM message emails include a stable message ID in the rate-limit key, so retries are suppressed without dropping subsequent messages. Ordinary channel invitations retain their sender/channel limit.
+
- Add a new invite email: new metadata type in `src/<name>.rs` deriving
`Template` → `templates/<name>.html` → `pub use` it from `src/lib.rs`.
- Change an email's markup: `templates/<name>.html` → preview with
diff --git a/crates/invite_email/src/lib.rs b/crates/invite_email/src/lib.rs
index 79947a7f31..c3308a2486 100644
--- a/crates/invite_email/src/lib.rs
+++ b/crates/invite_email/src/lib.rs
@@ -146,6 +146,13 @@ pub struct ChannelInviteMetadata {
/// Older notification payloads retain channel-invitation wording.
#[serde(default)]
pub is_direct_message: bool,
+ /// Stable DM message identity used while building the email delivery key.
+ /// The serialized email bundle carries the key; notification metadata does not.
+ #[serde(skip)]
+ pub message_id: Option<Uuid>,
+ /// Destination used while building a separate email retry key per recipient.
+ #[serde(skip)]
+ pub email_recipient: Option<MacroUserIdStr<'static>>,
/// Message content to show in the invite email, when the invite was triggered by a message.
#[serde(default)]
pub message_content: Option<String>,
@@ -216,6 +223,14 @@ impl NotificationExtEmail for ChannelInviteMetadata {
}
fn rate_limit_key(&self) -> RateLimitKey {
+ if self.is_direct_message
+ && let Some(message_id) = self.message_id
+ {
+ return RateLimitKey::builder(&Self::TYPE_NAME)
+ .append(&message_id)
+ .append(&self.email_recipient)
+ .finish();
+ }
RateLimitKey::builder(&Self::TYPE_NAME)
.append(&self.invited_by)
.append(&self.channel_name)
diff --git a/crates/invite_email/src/test.rs b/crates/invite_email/src/test.rs
index a89db5a0b4..48ce15961b 100644
--- a/crates/invite_email/src/test.rs
+++ b/crates/invite_email/src/test.rs
@@ -156,6 +156,8 @@ fn make_channel_invite() -> ChannelInviteMetadata {
invited_by: MacroUserIdStr::try_from_email("[email protected]").unwrap(),
channel_name: "general".to_string(),
is_direct_message: false,
+ message_id: None,
+ email_recipient: None,
message_content: None,
sender_profile_picture_url: None,
}
@@ -412,6 +414,47 @@ fn deserialization_without_sender_email_uses_none() {
assert!(deserialized.sender_email.is_none());
}
+#[test]
+fn dm_emails_deduplicate_retries_without_suppressing_later_messages() {
+ let first = ChannelInviteMetadata {
+ is_direct_message: true,
+ message_id: Some(Uuid::new_v4()),
+ ..make_channel_invite()
+ };
+ let other_recipient = ChannelInviteMetadata {
+ email_recipient: Some(MacroUserIdStr::try_from_email("[email protected]").unwrap()),
+ ..first.clone()
+ };
+ assert_ne!(
+ first.rate_limit_key().as_bytes(),
+ other_recipient.rate_limit_key().as_bytes()
+ );
+ let next = ChannelInviteMetadata {
+ message_id: Some(Uuid::new_v4()),
+ ..first.clone()
+ };
+ assert_eq!(
+ first.rate_limit_key().as_bytes(),
+ first.clone().rate_limit_key().as_bytes()
+ );
+ assert_ne!(
+ first.rate_limit_key().as_bytes(),
+ next.rate_limit_key().as_bytes()
+ );
+ let channel = ChannelInviteMetadata {
+ is_direct_message: false,
+ ..first
+ };
+ let next_channel = ChannelInviteMetadata {
+ is_direct_message: false,
+ ..next
+ };
+ assert_eq!(
+ channel.rate_limit_key().as_bytes(),
+ next_channel.rate_limit_key().as_bytes()
+ );
+}
+
fn make_team_invite(invitee_plan: InviteePlan) -> InviteToTeamMetadata {
InviteToTeamMetadata {
team_name: "Acme".to_string(),
diff --git a/docs/agent-guide/channels.md b/docs/agent-guide/channels.md
index d63a712506..c0f403508c 100644
--- a/docs/agent-guide/channels.md
+++ b/docs/agent-guide/channels.md
@@ -9,6 +9,16 @@ the message text, including link labels and mention names, once per preview.
Verify wide and narrow rows and channel/thread cards; links and mentions remain
interactive inside the opened conversation.
+## Empty direct messages
+
+An empty human DM shows the centered conversations illustration and “Say hello”
+above the composer. The copy explains that recipients without a Macro account
+receive the message by email. Opening the DM sends nothing. Sending a human
+message queues an immediate email for nonusers, including follow-up messages,
+replies, and mentions; registered users retain their notification preferences.
+Check narrow and wide panes: the composer stays usable, and the empty state
+vanishes when the first timeline entry appears. Agent DMs keep their own UI.
+
## Create a channel
1. `Create` → `Channel G`. Dialog `Create a channel` opens on step 1 of 3 with the `Name` textbox focused.
diff --git a/docs/proof/dm-empty-state/README.md b/docs/proof/dm-empty-state/README.md
new file mode 100644
index 0000000000..8a50472c2e
--- /dev/null
+++ b/docs/proof/dm-empty-state/README.md
@@ -0,0 +1,10 @@
+# Direct-message empty state
+
+Browser captures of `DirectMessageEmptyState` rendered with the app's real
+styles and shared illustration in an isolated component preview. The header and
+composer are preview scaffolding. Wide and 390px-wide panes were inspected;
+these captures do not demonstrate live message or email delivery.
+
+![Wide conversation](desktop.png)
+
+![Narrow conversation](narrow.png)
diff --git a/docs/proof/dm-empty-state/desktop.png b/docs/proof/dm-empty-state/desktop.png
new file mode 100644
index 0000000000..ba694c9e19
Binary files /dev/null and b/docs/proof/dm-empty-state/desktop.png differ
diff --git a/docs/proof/dm-empty-state/narrow.png b/docs/proof/dm-empty-state/narrow.png
new file mode 100644
index 0000000000..cb2d8facfe
Binary files /dev/null and b/docs/proof/dm-empty-state/narrow.png differ