Skip to content

Commit 4e1c474

Browse files
shahednassershahednasser
authored
docs: emails in cloud (#14040)
* docs: emails in cloud * add notes to user guides * small updates * small change * fix link * addressed feedback
1 parent 2c61a41 commit 4e1c474

File tree

15 files changed

+1174
-16
lines changed

15 files changed

+1174
-16
lines changed

‎www/apps/book/public/llms-full.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45683,6 +45683,8 @@ Then, place an order. The subscriber will run, sending a notification to the Med
4568345683

4568445684
In this document, you'll learn about the Notification Module and its providers.
4568545685

45686+
Cloud offers [Medusa Emails](https://docs.medusajs.com/cloud/emails/index.html.md), a managed email service that allows you to send transactional emails with zero configuration. It is built on top of the Notification Module and provides an easy way to manage email notifications in your Cloud projects with insights and deliverability features.
45687+
4568645688
## What is the Notification Module?
4568745689

4568845690
The Notification Module exposes the functionalities to send a notification to a customer or user. For example, sending an order confirmation email. Medusa uses the Notification Module in its core commerce features for notification operations, and you an use it in your custom features as well.
@@ -45917,6 +45919,8 @@ export const config: SubscriberConfig = {
4591745919

4591845920
The SendGrid Notification Module Provider integrates [SendGrid](https://sendgrid.com) to send emails to users and customers.
4591945921

45922+
Cloud offers [Medusa Emails](https://docs.medusajs.com/cloud/emails/index.html.md), a managed email service that allows you to send transactional emails with zero configuration. It is built on top of the Notification Module and provides an easy way to manage email notifications in your Cloud projects with insights and deliverability features.
45923+
4592045924
## Register the SendGrid Notification Module
4592145925

4592245926
### Prerequisites

‎www/apps/cloud/app/cache/page.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@ To enable Medusa Cache for your Medusa project deployed on Cloud, set the `cachi
3535
module.exports = defineConfig({
3636
// ...
3737
featureFlags: {
38-
caching: true
39-
}
38+
caching: true,
39+
},
4040
})
4141
```
4242

@@ -70,8 +70,8 @@ const { data: products } = await query.graph({
7070
fields: ["id", "title", "handle"],
7171
}, {
7272
cache: {
73-
enable: true
74-
}
73+
enable: true,
74+
},
7575
})
7676
```
7777

‎www/apps/cloud/app/emails/page.mdx‎

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
import { CodeTabs, CodeTab, Prerequisites, InlineIcon } from "docs-ui"
2+
import { ChevronUpDown } from "@medusajs/icons"
3+
4+
export const metadata = {
5+
title: `Medusa Emails`,
6+
}
7+
8+
# {metadata.title}
9+
10+
In this chapter, you'll learn about Medusa Emails and how to send emails in your Cloud projects.
11+
12+
## What is Medusa Emails?
13+
14+
Medusa Emails is a built-in email sending service for Cloud organizations and projects.
15+
16+
<Note title="Not a Cloud user yet?">
17+
18+
[Sign up for Cloud](../sign-up/page.mdx) to use Medusa Emails and other Cloud features.
19+
20+
</Note>
21+
22+
Medusa Emails allows you to send transactional and marketing emails like order confirmations directly from your Medusa application without needing to set up and manage your own email infrastructure.
23+
24+
Medusa Emails is available for all Cloud plans, with different sending limits based on your [plan](../pricing/page.mdx). You can use it out-of-the-box without manual configuration.
25+
26+
Through your organization's dashboard, you can also monitor email sending statistics and manage your email sender domain.
27+
28+
---
29+
30+
## Set Up Medusa Emails in Cloud Projects
31+
32+
Medusa Emails is enabled by default for all Cloud projects and organizations with zero configuration.
33+
34+
### Remove Other Email Notification Module Providers
35+
36+
Medusa enables Medusa Emails by default for all Cloud projects if you haven't configured a [Notification Module Provider](!resources!/infrastructure-modules/notification) for the `email` channel in your Medusa application.
37+
38+
So, if you have a notification provider like the [SendGrid Notification Module Provider](!resources!/infrastructure-modules/notification/sendgrid), remove it from your Medusa application to use Medusa Emails.
39+
40+
#### Local Development Email Setup
41+
42+
Since Medusa Emails isn't available for local development, you can set up the [Local Notification Module Provider](!resources!/infrastructure-modules/notification/local) to test email sending functionality in your local environment. This provider will log the email details to the console instead of sending them.
43+
44+
For example, you can add the following configuration to `medusa-config.ts`:
45+
46+
```ts title="medusa-config.ts"
47+
module.exports = defineConfig({
48+
// ...
49+
modules: [
50+
{
51+
resolve: "@medusajs/medusa/notification",
52+
options: {
53+
providers: [
54+
// ...
55+
{
56+
resolve: "@medusajs/medusa/notification-local",
57+
id: "local",
58+
options: {
59+
channels: [
60+
process.env.NODE_ENV === "development"
61+
? "email"
62+
: "feed",
63+
],
64+
},
65+
},
66+
],
67+
},
68+
},
69+
],
70+
})
71+
```
72+
73+
In this setup, the Local Notification Module Provider is used for the `email` channel only in the development environment. In other environments, it uses the `feed` channel.
74+
75+
### (Optional) Verify Your Email Sender Domain
76+
77+
By default, Medusa Emails sends emails using a randomly generated email address at the domain `medusajsemails.com`.
78+
79+
If you don't verify an email sender domain, you can only send emails to addresses of users in your Cloud organization.
80+
81+
To send emails to external email addresses, [verify your email sender domain](#verify-email-sender-domain-on-cloud).
82+
83+
---
84+
85+
## Send Emails on Cloud
86+
87+
To send emails using Medusa Emails in your Cloud project, create a notification that's sent through the `email` channel in your project's code.
88+
89+
For example:
90+
91+
<CodeTabs group="medusa-email-example">
92+
<CodeTab label="Workflow" value="workflow">
93+
94+
```ts
95+
import { createWorkflow } from "@medusajs/framework/workflows-sdk"
96+
import { sendNotificationsStep } from "@medusajs/medusa/core-flows"
97+
98+
type Input = {
99+
email: string
100+
}
101+
102+
const myWorkflow = createWorkflow(
103+
"my-workflow",
104+
(input: Input) => {
105+
const data = sendNotificationsStep({
106+
// must either have a verified sender domain or use an email
107+
// address that belongs to your Cloud organization
108+
to: input.email,
109+
channel: "email",
110+
content: {
111+
html: "<h1>Welcome to Medusa Emails!</h1><p>This is a test email sent using Medusa Emails in a Cloud project.</p>",
112+
subject: "Welcome to Medusa Emails",
113+
},
114+
})
115+
}
116+
)
117+
```
118+
119+
</CodeTab>
120+
<CodeTab label="Scheduled Job / Subscriber / API Route" value="job">
121+
122+
```ts
123+
import { Modules } from "@medusajs/framework/utils"
124+
125+
// ...
126+
127+
const notificationModuleService = container.resolve(
128+
Modules.NOTIFICATION
129+
)
130+
131+
await notificationModuleService.createNotifications({
132+
// must either have a verified sender domain or use an email
133+
// address that belongs to your Cloud organization
134+
to: "user@example.com",
135+
channel: "email",
136+
content: {
137+
html: "<h1>Welcome to Medusa Emails!</h1><p>This is a test email sent using Medusa Emails in a Cloud project.</p>",
138+
subject: "Welcome to Medusa Emails",
139+
},
140+
})
141+
```
142+
143+
</CodeTab>
144+
</CodeTabs>
145+
146+
When this code is executed in your Cloud project, Medusa sends the email using Medusa Emails. You can track whether the email was delivered on the [Email Activity page](#monitor-email-sending-activity-on-cloud).
147+
148+
### Writing Email Templates
149+
150+
To write email templates for Medusa Emails, use packages like [react-email](https://react.email). React Email lets you create email templates using React components with preview and testing capabilities.
151+
152+
Refer to the [Set Up React Email Templates](./react-email/page.mdx) guide to learn how to set up React Email templates in your Cloud project with examples.
153+
154+
---
155+
156+
## Verify Email Sender Domain on Cloud
157+
158+
<Prerequisites
159+
items={[
160+
{
161+
text: "A domain that you own and can access its DNS settings.",
162+
},
163+
]}
164+
/>
165+
166+
To send emails to external email addresses using Medusa Emails, you need to verify your email sender domain in your Cloud organization. You can verify multiple sender domains if needed.
167+
168+
To verify your email sender domain:
169+
170+
1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
171+
2. Click on the <InlineIcon Icon={ChevronUpDown} alt="switch organization" /> icon in the [organization switcher](../organizations/page.mdx#switch-organization) at the top left of the Cloud dashboard.
172+
3. Choose "Organization Settings" from the dropdown.
173+
174+
![Organization switcher dropdown opened](https://res.cloudinary.com/dza7lstvk/image/upload/v1750238273/Cloud/CleanShot_2025-06-18_at_12.17.33_2x_zcg69z.png)
175+
176+
4. Click Emails -> Sender Domains from the sidebar.
177+
5. Click the "Add sender domain" button.
178+
6. In the form that opens, perform these two steps:
179+
- **Domain**: Enter the domain you want to verify (for example, `yourdomain.com`).
180+
- **DNS Records**: Add the provided DNS records to your domain's DNS settings. These records are necessary for verifying domain ownership and setting up email authentication.
181+
- If you're unsure how to add DNS records, refer to your domain registrar's documentation or support.
182+
7. Once you're done, click the "I've added the records" button.
183+
184+
The domain will then be added, and the system will periodically check the DNS records to verify it. This process may take a few minutes to several hours, depending on your DNS provider.
185+
186+
![Sender Domains page with the sender domain added](https://res.cloudinary.com/dza7lstvk/image/upload/v1762947495/Cloud/CleanShot_2025-11-12_at_13.36.59_2x_sbaf7y.png)
187+
188+
### Specify From Email
189+
190+
After verifying your email sender domain, specify a `from` property in the notification to set the sender email address.
191+
192+
For example:
193+
194+
<CodeTabs group="medusa-email-from-example">
195+
<CodeTab label="Workflow" value="workflow">
196+
197+
```ts
198+
import { createWorkflow } from "@medusajs/framework/workflows-sdk"
199+
import { sendNotificationsStep } from "@medusajs/medusa/core-flows"
200+
201+
type Input = {
202+
email: string
203+
}
204+
205+
const myWorkflow = createWorkflow(
206+
"my-workflow",
207+
(input: Input) => {
208+
const data = sendNotificationsStep({
209+
to: input.email,
210+
from: "no-reply@yourdomain.com",
211+
channel: "email",
212+
content: {
213+
html: "<h1>Welcome to Medusa Emails!</h1><p>This is a test email sent using Medusa Emails in a Cloud project.</p>",
214+
subject: "Welcome to Medusa Emails",
215+
},
216+
})
217+
}
218+
)
219+
```
220+
221+
</CodeTab>
222+
<CodeTab label="Scheduled Job / Subscriber / API Route" value="job">
223+
224+
```ts
225+
import { Modules } from "@medusajs/framework/utils"
226+
227+
// ...
228+
229+
const notificationModuleService = container.resolve(
230+
Modules.NOTIFICATION
231+
)
232+
233+
await notificationModuleService.createNotifications({
234+
to: "user@example.com",
235+
from: "no-reply@yourdomain.com",
236+
channel: "email",
237+
content: {
238+
html: "<h1>Welcome to Medusa Emails!</h1><p>This is a test email sent using Medusa Emails in a Cloud project.</p>",
239+
subject: "Welcome to Medusa Emails",
240+
},
241+
})
242+
```
243+
244+
</CodeTab>
245+
</CodeTabs>
246+
247+
The email will be sent from the `no-reply@yourdomain.com` address, assuming it belongs to your verified sender domain.
248+
249+
---
250+
251+
## Monitor Email Sending Activity on Cloud
252+
253+
You can monitor email sending activity like sent emails, delivery rates, open rates, and click rates for your Cloud organization using the Email Activity page in your Cloud dashboard.
254+
255+
To view email sending activity:
256+
257+
1. Make sure you're viewing the [correct organization's dashboard in Cloud](../organizations/page.mdx#switch-organization).
258+
2. Click on the <InlineIcon Icon={ChevronUpDown} alt="switch organization" /> icon in the [organization switcher](../organizations/page.mdx#switch-organization) at the top left of the Cloud dashboard.
259+
3. Choose "Organization Settings" from the dropdown.
260+
4. Click Emails -> Activity from the sidebar.
261+
262+
At the top of the Email Activity page, you'll see email sending statistics for your organization across all projects, including:
263+
264+
- **Sent**: Total number of sent emails in the specified time range.
265+
- **Deliverability Rate**: Percentage of sent emails that were successfully delivered to recipients.
266+
- **Open Rate**: Percentage of delivered emails that were opened by recipients.
267+
- **Click Rate**: Percentage of opened emails where recipients clicked on links within the email.
268+
- **Bounce Rate**: Percentage of sent emails that were not delivered due to permanent delivery failures.
269+
- **Complaint Rate**: Percentage of sent emails that recipients marked as spam or junk.
270+
271+
Below the statistics, you'll find a detailed list of sent emails.
272+
273+
![Email Activity page showing email sending statistics and a list of sent emails](https://res.cloudinary.com/dza7lstvk/image/upload/v1762948757/Cloud/CleanShot_2025-11-12_at_13.59.02_2x_uetth1.png)
274+
275+
### Change Email Activity Time Range
276+
277+
To change the time range for email activity statistics and the list of sent emails, click the time range dropdown at the top right of the page. You can choose custom ranges or predefined ranges like "Last 7 days" or "Last 30 days".
278+
279+
![Time range dropdown opened on the Email Activity page](https://res.cloudinary.com/dza7lstvk/image/upload/v1762948832/Cloud/CleanShot_2025-11-12_at_14.00.17_2x_bqlopg.png)
280+
281+
### Filter Emails by Project
282+
283+
By default, the Email Activity page shows emails from all projects in your Cloud organization.
284+
285+
To filter emails by a specific project, click the "All projects" dropdown at the top right of the page and select the desired project.
286+
287+
This updates the email sending statistics and list to show only emails from the selected project.
288+
289+
![Project filter dropdown opened on the Email Activity page](https://res.cloudinary.com/dza7lstvk/image/upload/v1762948832/Cloud/CleanShot_2025-11-12_at_14.00.17_2x_bqlopg.png)
290+
291+
### View Email Details
292+
293+
To view an email's details, click the email entry in the list on the Email Activity page.
294+
295+
At the top of the Email Details page, you'll see an overview of the email's event history, including when it was sent, delivered, opened, and when its links were clicked.
296+
297+
Below that, you'll see a preview of the email content as it was sent to the recipient, with support for both HTML and plain text views.
298+
299+
![Email Details page showing the email's event history and a preview of the email content](https://res.cloudinary.com/dza7lstvk/image/upload/v1762950939/Cloud/CleanShot_2025-11-12_at_14.03.33_2x_tv6ydx.png)
300+
301+
---
302+
303+
## Troubleshoot Email Delivery Issues on Cloud
304+
305+
If you try to send an email using Medusa Emails in your Cloud project and it's not delivered, consider these troubleshooting steps:
306+
307+
1. **Check Email Activity**: Go to the [Email Activity page](#monitor-email-sending-activity-on-cloud) in your Cloud organization's dashboard to see if the email appears in the list. If it does, check its status and event history for delivery issues.
308+
2. **Verify Sender Domain**: If you're sending emails to external addresses, ensure you've verified your email sender domain in your Cloud organization. Without a verified sender domain, you can only send emails to addresses in your Cloud organization.
309+
3. **Check Logs**: Review your project's [logs](../logs/page.mdx#view-runtime-logs-on-cloud) for errors or warnings related to email sending. Look for issues that might indicate why the email wasn't sent or delivered.
310+
4. **Check Spam/Junk Folder**: Ask the recipient to check their spam or junk email folder. Sometimes emails may be incorrectly marked as spam by email providers.
311+
5. **Contact Support**: If you've tried the above steps and are still experiencing issues, contact support for assistance.

0 commit comments

Comments
 (0)