All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

More jobs like this: Hand off a long task

Keep reading