# Send an Order Confirmation Email from a Medusa Backend

Yes. An agent adds an order.placed subscriber, a workflow that builds the email from the order, a notification provider and tests to your Medusa backend, in a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-order-confirmation-email/medusa/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the backend is laid out before it adds an event handler, because Medusa 2 has a place for each kind of code and a subscriber that calls a mail API directly is the thing the framework is designed to avoid. In a project laid out like medusajs/dtc-starter, `apps/backend` runs `@medusajs/medusa` 2.22.1 with `medusa develop`, `medusa build` and `medusa lint`, and `AGENTS.md` at the root maps each task to a directory: events in `src/subscribers/`, business logic in `src/workflows/`, module configuration in `medusa-config.ts`. Those two directories hold only a `README.md` each, so no subscriber or custom workflow exists yet. `medusa-config.ts` sets the database URL, CORS and the two secrets and declares no modules, so the Notification Module runs with no provider. `src/api/middlewares.ts` configures store search, `src/migration-scripts/initial-data-seed.ts` creates regions, sales channels, shipping options and products through core flows, and `apps/storefront` is a Next.js 16 store with a multi-step checkout, so `order.placed` is emitted by the checkout's complete-cart flow. `jest.config.js` selects tests by `TEST_TYPE`, with HTTP integration tests under `integration-tests/http/` and unit tests under `src/**/__tests__/`.

The agent writes `src/subscribers/order-placed.ts`, which exports a handler whose `config.event` is `order.placed` and which does nothing but run a workflow with the order id from `event.data`. The workflow, `src/workflows/send-order-confirmation.ts`, is built with `createWorkflow` and two steps: `useQueryGraphStep` to read the order with its `email`, `display_id`, `currency_code`, `total`, `items` with `title`, `quantity` and `unit_price`, `shipping_address` and `shipping_methods`, and `sendNotificationsStep` from core flows to create a notification on the `email` channel with the template name and that data. A small `src/modules/email-templates/` folder renders the order into HTML and text so the provider only sends.

In `medusa-config.ts` the Notification Module gets a provider: the built-in SendGrid provider for a team that has a SendGrid account, configured from `SENDGRID_API_KEY` and `SENDGRID_FROM` with a template id, or the local provider, which logs the notification, for a team that has not picked a service yet. The agent picks the local provider so the pull request runs anywhere, and leaves the SendGrid block in a comment with the variables it needs, because which service to use is the team's call and not the agent's. The new variables go into `.env.template`.

To check it, the agent starts Postgres in its sandbox, runs the migrations and the seed, and writes two tests: a unit test under `src/workflows/__tests__/` that runs the workflow against the test container with a seeded order and asserts the notification's recipient, template and line items, and an HTTP integration test that completes a cart through the store API and asserts the notification was created. It runs `medusa lint`, `medusa build`, `test:unit` and `test:integration:http`, and pastes the rendered email for the seeded order into the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Send an order confirmation email from this Medusa backend. Read AGENTS.md, apps/backend/medusa-config.ts, apps/backend/package.json, apps/backend/.env.template, apps/backend/src/subscribers/README.md, apps/backend/src/workflows/README.md, apps/backend/src/api/middlewares.ts, apps/backend/src/migration-scripts/initial-data-seed.ts, apps/backend/jest.config.js and apps/backend/integration-tests/ first. Add an order.placed subscriber that only runs a workflow with the order id; a workflow that reads the order with its email, display id, totals, items, shipping address and shipping method through the query graph and creates a notification on the email channel with a rendered HTML and text body; a notification provider in medusa-config.ts, using the local provider so the change runs anywhere and leaving the SendGrid configuration commented with the variables it needs; and the variables in .env.template. Write a unit test for the workflow against a seeded order and an HTTP integration test that completes a cart and asserts the notification. Start Postgres in your sandbox, run migrations and the seed, run lint, build and both test types, paste the rendered email, and open a pull request with the output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `apps/backend/medusa-config.ts` and `apps/backend/.env.template` and adds `src/subscribers/order-placed.ts`, `src/workflows/send-order-confirmation.ts`, the template module, a unit test and an HTTP integration test. Its description shows the rendered email for a seeded order, the `medusa lint` and `medusa build` output, both test runs, and the commented SendGrid block with the variables a team needs to switch providers.

The subscriber runs on every `order.placed` the backend emits, whichever storefront or admin action placed the order, and the workflow is a named unit the admin can retry if the provider fails. The checkout, the storefront and the existing search middleware are unchanged; the `Update Medusa` workflow in `.github/workflows` is untouched.

Before merging, a reviewer reads the email copy, picks the provider and sets its secrets in the deployment, decides whether the template should also cover `order.updated` or shipment events, and checks the workflow's retry setting so a provider outage does not drop a confirmation.

## Run it on every order placed

Once merged, the backend itself sends an email per order, so no Rush run is needed per event. The run worth repeating is the one that keeps the template honest: a `schedule` trigger on an automation starts a run each Monday morning that reads the week's `order.placed` notifications through the admin API, checks each one rendered with the right currency and totals, and reports the ones that did not, with the order ids. A `linear` trigger on an automation can start a run from an issue labelled `email-template`, with the issue added to the prompt after it, so a copy change arrives as a pull request.

An automation run has its own `max_runs_per_hour` cap and is not tied to an API key. A team that would rather start the report by hand sends a body like this one with a `request_id` that is a UUID v5 of the week's start date, so a retried call returns the run already started.

## Why run it on Rush?

The email is the first thing a customer sees after paying, and getting it out of a Medusa 2 backend means knowing the module system: where the event is emitted, how a workflow reads an order through the query graph, and how a notification reaches a provider. The agent follows the repository's own `AGENTS.md`, writes each piece where the framework expects it, and proves the whole path with a completed cart in its own sandbox.

The migrations, the seed, both test runs and the rendered email stay with the run and are pasted into the pull request, so the review is about the copy and the provider rather than whether the event fires. Several backends can get the same flow at once, each with its own order shape.

## Frequently asked questions

### Why go through a workflow instead of sending from the subscriber?

A subscriber that calls a mail API directly has no retry, no record and no way to swap the provider. A workflow step that creates a notification is retried by the engine, shows up in the admin, and lets the provider change in `medusa-config.ts` without touching the email logic.

### Which email service does it use?

The pull request configures the local provider, which logs the notification, so it runs in CI and in any environment. The SendGrid provider block is in a comment with the variables it needs; a team on another service plugs in that service's provider in the same place.

### Does the storefront need to change?

No. The event is emitted by the complete-cart flow on the backend whichever client calls it, so the Next.js storefront, a mobile app or an admin-created order all result in the same email.

### Will it email on test orders?

Yes, every `order.placed`. The workflow's template includes the display id and the sales channel, so a team that wants to skip a test channel adds one condition in the subscriber, and the pull request shows where.

## More Medusa jobs

- [Add Product Reviews to a Medusa Store](https://getrush.ai/run/add-product-reviews/medusa/)
- [Add Rate Limiting to a Medusa Store API](https://getrush.ai/run/add-rate-limiting/medusa/)
- [Set Up Redis for a Medusa Backend](https://getrush.ai/run/add-redis/medusa/)

## More jobs like this: Hand off a long task

- [Add Over-the-Air Updates to an Expo App](https://getrush.ai/run/add-ota-updates/expo/)
- [Add an OTLP Exporter for Your Own Backend to the OpenTelemetry Collector](https://getrush.ai/run/add-otlp-exporter/opentelemetry/)
- [Add Output Caching to an ASP.NET Core Minimal API](https://getrush.ai/run/add-output-caching/dotnet/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
