@spree/docs 0.1.268 → 0.1.270

package/dist/developer/core-concepts/store-credits-gift-cards.md

@@ -399,6 +399,8 @@ Store Credits and Gift Cards work differently at checkout:
 - **Store Credits** - Require a customer account; applied from the customer's balance
 - **Gift Cards** - Can be used by anyone (guests included); applied directly to the order via code
 
+Both are applied before the customer chooses how to pay, and neither appears among the cart's payment methods. An order uses one or the other, never both. A gift card covers as much of the total as its balance allows and keeps up as the total changes. See the [cart & checkout SDK guide](../sdk/store/cart-checkout.md) for the calls.
+
 ### Checkout Flow
 
 ```mermaid

package/dist/developer/deployment/emails.md

@@ -13,7 +13,7 @@ Spree handles two categories of emails:
 
 ## Customer-Facing Emails
 
-By default, **Spree sends all customer transactional emails itself** — the `spree_emails` gem ships installed in every deployment. This works for every client of the API: mobile apps, custom frontends, POS integrations — no storefront required. Delivery uses the same [SMTP configuration](#configuration) as system emails.
+By default, **Spree sends all customer transactional emails itself**. This works for every client of the API: mobile apps, custom frontends, POS integrations — no storefront required. Delivery uses the same [SMTP configuration](#configuration) as system emails.
 
 Customer emails can be turned off in the admin under **Settings → Emails** — do this when your storefront takes over sending them (below), otherwise customers receive both.
 
@@ -89,10 +89,12 @@ Set the following environment variables on the **Spree backend** to enable email
 | `SMTP_USERNAME` | — | SMTP auth username |
 | `SMTP_PASSWORD` | — | SMTP auth password |
 | `SMTP_FROM_ADDRESS` | — | Default "from" email address (e.g., `admin@mystore.com`) |
-| `RAILS_HOST` | `example.com` | Public host used in email links and other [generated URLs](environment_variables.md#urls-and-hosts) — image/attachment URLs use `CDN_HOST` instead when set |
+| `SPREE_HOST` | `example.com` | Public host used in email links and other [generated URLs](environment_variables.md#urls-and-hosts) — image/attachment URLs use `CDN_HOST` instead when set |
 
 When `SMTP_HOST` is not set, emails are printed to the Rails log instead of being sent.
 
+Any SMTP provider works — there is nothing provider-specific to install. For how the configuration behaves and what to weigh when choosing between providers, see [Emails](../providers/emails.md). Step-by-step setup for each one: [Resend](../../integrations/email/resend.md), [Postmark](../../integrations/email/postmark.md), [SendGrid](../../integrations/email/sendgrid.md), [Mailgun](../../integrations/email/mailgun.md) and [Amazon SES](../../integrations/email/amazon-ses.md).
+
 ### Provider Examples
 
 **SendGrid:**

package/dist/developer/providers/emails.md

@@ -0,0 +1,79 @@
+---
+title: Emails
+description: Spree sends transactional email over plain SMTP, configured entirely by environment variable — any provider works, and none of them needs anything installed.
+---
+
+Every transactional email Spree sends — order confirmations, shipping notifications, password resets, staff invitations — goes out over SMTP. There is nothing to install and no integration to connect: you give Spree an SMTP host and credentials through environment variables, and it sends.
+
+This makes email the one provider category that is **not** configured per store in the admin. Payment gateways, tax engines and search each hold their credentials as a [store integration](overview.md); email is infrastructure for the whole deployment, so it lives in the environment alongside the database URL.
+
+For what Spree sends, when, and how a storefront can take the customer-facing mail over instead, see [Sending out Emails](../deployment/emails.md).
+
+## Configuration
+
+Set these on the Spree backend:
+
+```bash
+SMTP_HOST=smtp.resend.com
+SMTP_PORT=587
+SMTP_USERNAME=resend
+SMTP_PASSWORD=re_your_api_key
+SMTP_FROM_ADDRESS=orders@yourstore.com
+```
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `SMTP_HOST` | — | The provider's SMTP server. **Setting this is what turns on SMTP delivery** — leave it unset and nothing is configured |
+| `SMTP_PORT` | `587` | The port to connect on |
+| `SMTP_USERNAME` | — | The SMTP user. Optional: when it is absent Spree connects without authenticating |
+| `SMTP_PASSWORD` | — | The SMTP password, sent only when a username is set |
+| `SMTP_FROM_ADDRESS` | — | The default From address on outgoing mail |
+| `SPREE_HOST` | `example.com` | The public host used to build links inside emails — see [environment variables](../deployment/environment_variables.md#urls-and-hosts) |
+
+Two details are worth knowing because they decide whether a provider will accept your connection at all:
+
+- **STARTTLS is always attempted.** Spree upgrades the connection to TLS whenever the server offers it, which is what every provider below expects on port 587. It does not open a connection that is implicitly TLS from the first byte, so a provider's "SSL" port — usually 465 — is the wrong choice here. Use the STARTTLS port.
+- **Authentication is optional, and plain when used.** Credentials are sent only if `SMTP_USERNAME` is set, which is how the quickstart delivers to a local mail catcher with no account at all. When it is set, Spree authenticates with the `plain` mechanism over the encrypted connection — the one every provider below documents for SMTP.
+
+> **NOTE:** `SMTP_FROM_ADDRESS` sets the application-wide default. Merchants can override the From and Reply-To addresses per store in the admin under **Settings → Emails** — see the [email settings guide](/user/settings/emails).
+
+## Choosing a provider
+
+Any service that speaks SMTP works. Because the integration is identical, the choice is about everything *around* sending rather than anything in Spree:
+
+- **Deliverability and reputation.** Whether mail lands in the inbox is mostly the provider's IP reputation plus your domain authentication, not your code.
+- **Domain authentication.** Every provider will ask you to prove you own your sending domain with DNS records. This is the single highest-value thing you can do for deliverability, and it is not optional in practice.
+- **Sending limits and pricing.** Free and trial tiers are usually capped by volume, and several restrict *who* you may send to until you verify a domain.
+- **Bounces and complaints.** Spree does not process bounce notifications. Handling a hard bounce or a spam complaint is the provider's dashboard and webhooks, which differ a lot between them.
+- **Analytics.** Open and click tracking, message logs and retention are provider features.
+
+
+  - [Resend](../../integrations/email/resend.md) — Developer-focused and quick to set up.
+  - [Postmark](../../integrations/email/postmark.md) — Built around transactional mail and fast delivery.
+  - [SendGrid](../../integrations/email/sendgrid.md) — Long-established, high volume.
+  - [Mailgun](../../integrations/email/mailgun.md) — Flexible routing, US and EU regions.
+  - [Amazon SES](../../integrations/email/amazon-ses.md) — Cheapest at scale if you already run on AWS.
+
+
+## Verifying delivery
+
+After setting the variables and restarting the application, send a real message rather than trusting the configuration:
+
+1. Trigger an email — inviting a staff member under **Settings → Users** is the quickest, since it needs no order.
+2. Check the provider's own activity or message log. This is the honest answer: it tells you whether the provider accepted the message, and whether it then bounced.
+3. If nothing arrives, read the application logs. An SMTP rejection surfaces there with the provider's own error text, which normally names the cause — an unverified sender, a bad credential, or a sandbox restriction.
+
+The most common failures are not configuration mistakes in Spree:
+
+| Symptom | Usual cause |
+| --- | --- |
+| Emails are written to the log instead of sent | `SMTP_HOST` is not set, so SMTP delivery was never switched on |
+| Authentication fails | The username is not what the provider expects — several want a fixed literal rather than your account email |
+| The provider rejects the sender | `SMTP_FROM_ADDRESS` is a domain you have not authenticated with that provider |
+| Mail is accepted but never arrives | A new account restricted to verified recipients, or mail landing in spam because the domain is not authenticated |
+
+> **NOTE:** **Every provider restricts new accounts**, so a first test email that never arrives is usually the account, not your configuration. Amazon SES starts in a sandbox that only reaches verified addresses, Postmark reviews accounts before they can mail customers, Mailgun's sandbox reaches five named recipients, and Resend only emails you until a domain is verified. Authenticate your domain and clear the provider's restriction before treating a missing email as a bug.
+
+## Local development
+
+In development nothing is delivered externally. Emails are captured by [Mailpit](https://mailpit.axllent.org), which you read at `http://localhost:8025`. To exercise a real provider locally, set `SMTP_HOST` and the rest in `.env` — but point `SMTP_FROM_ADDRESS` at a domain you have authenticated, or the provider will reject it.

package/dist/developer/sdk/store/cart-checkout.md

@@ -77,6 +77,8 @@ const cart = await client.carts.giftCards.apply(cartId, 'GC-ABCD-1234', options)
 await client.carts.giftCards.remove(cartId, 'gc_abc123', options);
 ```
 
+A gift card pays as much of the total as its balance allows, and its share keeps up when delivery, discounts or tax change the total. A cart can use a gift card or store credit, not both.
+
 ### Fees and Duties
 
 A cart may carry charges that are neither a product price nor tax: gift wrapping, a handling charge, a cash-on-delivery surcharge, or an import duty on a cross-border order. Each is a [fee](../../core-concepts/fees.md) on the cart, and the storefront should show every one of them before the customer pays.
@@ -174,6 +176,8 @@ await client.carts.storeCredits.apply(cartId, 25.00, options);
 await client.carts.storeCredits.remove(cartId, options);
 ```
 
+Store credit is a balance, not one of the cart's `payment_methods`: apply it here, then collect whatever `amount_due` is left with a payment method. It can't be combined with a gift card on the same cart.
+
 ### Totals
 
 The cart and order responses break the amount the customer pays into these totals. Each has a raw string value and a `display_` twin formatted in the cart's currency.

package/dist/integrations/email/amazon-ses.md

@@ -0,0 +1,69 @@
+---
+title: Amazon SES
+description: Send Spree's transactional emails through Amazon SES over SMTP — regional endpoints, credentials that are not your IAM keys, and the sandbox to leave before launch.
+---
+
+[Amazon SES](https://aws.amazon.com/ses/) is AWS's email service and the cheapest option at volume. It is the natural choice for a store already running on AWS, at the cost of more setup than the other providers: credentials work differently from the rest of AWS, and every new account starts restricted.
+
+Spree talks to SES over plain SMTP, so there is nothing to install — see [Emails](../../developer/providers/emails.md) for how the configuration works.
+
+## Configuration
+
+```bash
+SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+SMTP_PORT=587
+SMTP_USERNAME=your_ses_smtp_username
+SMTP_PASSWORD=your_ses_smtp_password
+SMTP_FROM_ADDRESS=orders@yourstore.com
+```
+
+The host follows the pattern `email-smtp.<region>.amazonaws.com`. Pick the region you verified your domain in — credentials are **per region**, so a key made in one region will not authenticate in another:
+
+| Region | SMTP endpoint |
+| --- | --- |
+| `us-east-1` (N. Virginia) | `email-smtp.us-east-1.amazonaws.com` |
+| `us-west-2` (Oregon) | `email-smtp.us-west-2.amazonaws.com` |
+| `eu-west-1` (Ireland) | `email-smtp.eu-west-1.amazonaws.com` |
+| `eu-central-1` (Frankfurt) | `email-smtp.eu-central-1.amazonaws.com` |
+| `ap-southeast-2` (Sydney) | `email-smtp.ap-southeast-2.amazonaws.com` |
+
+**Not every SES region has an SMTP endpoint.** Cape Town, Hyderabad, Jakarta, Malaysia, Milan, Zurich, Tel Aviv, Bahrain, UAE and Calgary offer the SES API but no SMTP host, so a region that works for the API may not work here — check the [SES endpoints reference](https://docs.aws.amazon.com/general/latest/gr/ses.html#ses_smtp_endpoints) before settling on one.
+
+Use port 587 (or 25 or 2587) for STARTTLS; 465 and 2465 are implicit TLS, which Spree does not use. SES requires TLS on every connection, so there is no unencrypted option to fall back to.
+
+## Getting SMTP credentials
+
+> **WARNING:** **SES SMTP credentials are not your AWS access keys.** As AWS puts it, "Your SMTP password is different from your AWS secret access key." Pasting an IAM secret key into `SMTP_PASSWORD` fails to authenticate — the password is derived from that secret by a signing algorithm that takes the **region** as an input. A password derived for `us-east-1` will not authenticate against `eu-west-1`, which is why credentials cannot be shared between regions. Temporary credentials from STS cannot be used at all.
+
+Create them in the console rather than deriving them by hand:
+
+1. Open the SES console and choose **SMTP settings**.
+2. Choose **Create SMTP Credentials**, which opens IAM and creates a user for sending.
+3. Reveal the SMTP password, then **Download .csv file**. You cannot view the password again after closing the dialog.
+
+Repeat this for each region you send from.
+
+## Authenticating your domain
+
+In the SES console, go to **Identities** and create an identity for your domain. SES generates DKIM `CNAME` records to add at your DNS host, and verifying the domain also makes production access easier to obtain. Once verified, set `SMTP_FROM_ADDRESS` to an address on it.
+
+Verifying a domain is required regardless of sandbox status: even in production, you must verify every identity used as a From, Source, Sender or Return-Path address.
+
+## Leaving the sandbox
+
+Every new SES account starts in the **sandbox**, per region, and the restrictions make a live store impossible:
+
+- You can send only **to verified addresses and domains**, so real customers never receive anything.
+- A maximum of **200 recipients per rolling 24-hour period** — a message to several recipients counts once for each of them.
+- A maximum of **1 message per second**.
+
+To request production access, open the SES console, go to **Account dashboard**, and choose **Request production access**. You describe your mail as transactional, give your website URL, and confirm you handle bounces and complaints. AWS responds within 24 hours. Verifying your domain first helps the request get approved faster.
+
+> **NOTE:** Sending from EC2 adds one more step: EC2 throttles port 25 by default. Using port 587 as shown above avoids it.
+
+## Related
+
+- [Emails](../../developer/providers/emails.md) — the SMTP variables and how to verify delivery
+- [Sending out Emails](../../developer/deployment/emails.md) — what Spree sends and when
+- [Deploying Spree on AWS](../../developer/deployment/aws.md)
+- [SES SMTP credentials documentation](https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html)

package/dist/integrations/email/mailgun.md

@@ -0,0 +1,51 @@
+---
+title: Mailgun
+description: Send Spree's transactional emails through Mailgun over SMTP — per-domain credentials, separate US and EU regions, and a sandbox that only emails people you name.
+---
+
+[Mailgun](https://www.mailgun.com) is a long-established email API with flexible routing and a choice of US or EU infrastructure. The EU region makes it a common pick for stores that need their email data to stay in Europe.
+
+Spree talks to Mailgun over plain SMTP, so there is nothing to install — see [Emails](../../developer/providers/emails.md) for how the configuration works.
+
+## Configuration
+
+```bash
+SMTP_HOST=smtp.mailgun.org
+SMTP_PORT=587
+SMTP_USERNAME=postmaster@mg.yourstore.com
+SMTP_PASSWORD=your_smtp_password
+SMTP_FROM_ADDRESS=orders@yourstore.com
+```
+
+The username is a full address at your Mailgun sending domain, usually the `postmaster@` mailbox Mailgun creates for you.
+
+**Pick the right region.** Mailgun runs the US and EU as separate infrastructure, and an account in one is invisible to the other:
+
+| Region | SMTP host |
+| --- | --- |
+| US | `smtp.mailgun.org` |
+| EU | `smtp.eu.mailgun.org` |
+
+Mailgun listens on ports 25, 587 and 2525 for STARTTLS, and 465 for implicit TLS, which Spree does not use. Mailgun recommends 587, since some ISPs block or throttle port 25.
+
+## Getting SMTP credentials
+
+Credentials are set per domain, not per account:
+
+1. In the Mailgun dashboard, open your sending domain's settings.
+2. Find its **SMTP credentials**.
+3. Copy the username, and reset the password to reveal a new one.
+
+Because each domain has its own credentials, make sure the ones you use match the domain in `SMTP_FROM_ADDRESS`.
+
+## Authenticating your domain
+
+Add your sending domain under **Sending → Domains**. Mailgun asks for TXT records for SPF and DKIM, and CNAME records for tracking. Most setups use a subdomain such as `mg.yourstore.com`, which keeps Mailgun's records away from your main domain's mail. Once the domain verifies, set `SMTP_FROM_ADDRESS` to an address on it.
+
+> **WARNING:** **The sandbox domain only emails people you list.** Every new account gets a `sandbox….mailgun.org` domain that can send only to **authorized recipients**, capped at five addresses, each of which must accept an invitation. It is for testing — a store using the sandbox silently fails to reach every customer. Add and verify your own domain, and point `SMTP_HOST`, the credentials and `SMTP_FROM_ADDRESS` at it before taking orders.
+
+## Related
+
+- [Emails](../../developer/providers/emails.md) — the SMTP variables and how to verify delivery
+- [Sending out Emails](../../developer/deployment/emails.md) — what Spree sends and when
+- [Mailgun SMTP documentation](https://documentation.mailgun.com/docs/mailgun/user-manual/sending-messages/send-smtp)

package/dist/integrations/email/postmark.md

@@ -0,0 +1,45 @@
+---
+title: Postmark
+description: Send Spree's transactional emails through Postmark over SMTP — the Server API Token is both username and password, and transactional mail has its own stream.
+---
+
+[Postmark](https://postmarkapp.com) specialises in transactional email and is known for fast, reliable delivery. It keeps transactional and bulk mail strictly apart, which is a good fit for a store whose email is entirely order confirmations, shipping notices and password resets.
+
+Spree talks to Postmark over plain SMTP, so there is nothing to install — see [Emails](../../developer/providers/emails.md) for how the configuration works.
+
+## Configuration
+
+```bash
+SMTP_HOST=smtp.postmarkapp.com
+SMTP_PORT=587
+SMTP_USERNAME=your_server_api_token
+SMTP_PASSWORD=your_server_api_token
+SMTP_FROM_ADDRESS=orders@yourstore.com
+```
+
+> **NOTE:** The **Server API Token goes in both the username and the password field** — the same value twice. This looks like a mistake but is exactly what Postmark documents.
+
+Postmark accepts ports 25, 587 and 2525, all using STARTTLS. Use 587 unless your host blocks it, in which case 2525 is the usual fallback. Postmark has **no implicit-TLS port** — setting `SMTP_PORT=465` out of habit produces a connection that hangs rather than a clear error.
+
+## Getting a Server API Token
+
+1. In the Postmark dashboard, open the server you want to send from.
+2. Go to the **API Tokens** tab and copy the **Server API Token**.
+
+Tokens are per server, so mail from each server is tracked and rate-limited separately. A separate server for staging keeps test mail out of your production activity log.
+
+## Message streams
+
+Postmark separates **transactional** streams from **broadcast** streams, and keeps their reputations apart. Mail sent through `smtp.postmarkapp.com` with a Server API Token goes to the default transactional stream unless a header says otherwise, which is what a Spree store wants — there is nothing to configure. Broadcast mail uses a different host, `smtp-broadcasts.postmarkapp.com`, which Spree does not need.
+
+## Authenticating your domain
+
+Go to **Sender Signatures → Add Domain**, then add the DKIM and Return-Path records Postmark generates at your DNS host. Once verified, set `SMTP_FROM_ADDRESS` to an address on that domain.
+
+> **WARNING:** **New Postmark accounts are reviewed before they can send to customers.** Until the account is approved you can only send to domains you have added and verified, which behaves much like a sandbox: real customer addresses are refused. Approval usually takes under a day on weekdays, and only the account owner can request it. Ask as soon as you create the account rather than on launch day, and be ready to describe what your store sends — Postmark enforces its transactional-only policy more strictly than most providers.
+
+## Related
+
+- [Emails](../../developer/providers/emails.md) — the SMTP variables and how to verify delivery
+- [Sending out Emails](../../developer/deployment/emails.md) — what Spree sends and when
+- [Postmark SMTP documentation](https://postmarkapp.com/developer/user-guide/send-email-with-smtp)

package/dist/integrations/email/resend.md

@@ -0,0 +1,52 @@
+---
+title: Resend
+description: Send Spree's transactional emails through Resend over SMTP — one hostname, the literal username `resend`, and your API key as the password.
+---
+
+[Resend](https://resend.com) is a transactional email service built for developers, with a deliberately small setup: add a domain, create an API key, and send. It is a good default for a new Spree store that wants working email quickly without a long account review.
+
+Spree talks to Resend over plain SMTP, so there is nothing to install — see [Emails](../../developer/providers/emails.md) for how the configuration works.
+
+## Configuration
+
+```bash
+SMTP_HOST=smtp.resend.com
+SMTP_PORT=587
+SMTP_USERNAME=resend
+SMTP_PASSWORD=re_your_api_key
+SMTP_FROM_ADDRESS=orders@yourstore.com
+```
+
+The username is the **literal string `resend`** — not your email address and not the API key. The API key goes in the password field.
+
+Resend also accepts ports 25 and 2587 for STARTTLS. Ports 465 and 2465 are implicit TLS, which Spree does not use, so stay on 587.
+
+## Getting an API key
+
+1. Open the Resend dashboard and go to **API Keys**.
+2. Create a key with sending permission.
+3. Copy it immediately — the full value is shown only once. Keys start with `re_`.
+
+## Authenticating your domain
+
+Go to **Domains → Add Domain**, enter your sending domain, and add the records Resend generates at your DNS host:
+
+- **DKIM**, which proves the mail is really yours.
+- **SPF**, plus a record on the sending subdomain that routes bounces back to Resend.
+
+Create each one with the **type Resend displays**. Older domains are given `TXT`
+and `MX` records for SPF, where domains added after August 2026 may get `CNAME`
+records instead — so copy what the dashboard shows rather than assuming a type.
+On older domains both SPF records must be right or SPF does not verify at all.
+
+Once the domain shows as verified, set `SMTP_FROM_ADDRESS` to an address on it. A verified domain already passes SPF and DKIM; **DMARC** is not needed to verify, but is worth adding afterwards.
+
+> **WARNING:** **Until you verify a domain, you can only email yourself.** An unverified account sends from `onboarding@resend.dev`, and Resend restricts that test sender to the address on your own Resend account — anything else is refused with "You can only send testing emails to your own email address". A store in this state appears to work while no customer ever receives an order confirmation, so verify your domain before going live.
+
+> **NOTE:** Resend's free tier allows 3,000 emails a month but also caps sending at **100 a day**. A busy day of confirmations and shipping notices can reach that ceiling well before the monthly allowance, so check the daily figure rather than the monthly one when sizing a plan.
+
+## Related
+
+- [Emails](../../developer/providers/emails.md) — the SMTP variables and how to verify delivery
+- [Sending out Emails](../../developer/deployment/emails.md) — what Spree sends and when
+- [Resend SMTP documentation](https://resend.com/docs/send-with-smtp)

package/dist/integrations/email/sendgrid.md

@@ -0,0 +1,44 @@
+---
+title: SendGrid
+description: Send Spree's transactional emails through Twilio SendGrid over SMTP — the username is always the literal string `apikey`, with your API key as the password.
+---
+
+[Twilio SendGrid](https://sendgrid.com) is one of the longest-established email platforms, built for high volume with detailed analytics and a mature deliverability toolset. It suits stores already sending a lot of mail, or teams that want SendGrid's reporting alongside its API.
+
+Spree talks to SendGrid over plain SMTP, so there is nothing to install — see [Emails](../../developer/providers/emails.md) for how the configuration works.
+
+## Configuration
+
+```bash
+SMTP_HOST=smtp.sendgrid.net
+SMTP_PORT=587
+SMTP_USERNAME=apikey
+SMTP_PASSWORD=SG.your_api_key
+SMTP_FROM_ADDRESS=orders@yourstore.com
+```
+
+> **NOTE:** The username is the **literal string `apikey`**, exactly as written above — not your SendGrid username, and not the key itself. SendGrid's own wording: "This setting is the exact string `apikey` and not the API key itself." Your API key goes in the password field, used as-is: the Base64 encoding SendGrid mentions elsewhere applies to testing by hand with `openssl`, not to an application connecting over SMTP.
+
+SendGrid recommends port 587, which avoids the rate limiting and connection blocking some ISPs and hosting providers apply to port 25.
+
+## Getting an API key
+
+1. In the SendGrid dashboard go to **Settings → API Keys** and choose **Create API Key**.
+2. Give it **Mail Send** permission — that is all Spree needs, and a restricted key limits the damage if it leaks.
+3. Copy the key immediately; it is shown only once.
+
+## Authenticating your domain
+
+Go to **Settings → Sender Authentication** and complete **Domain Authentication**. SendGrid generates CNAME records to add at your DNS host, covering DKIM signing and the return path. Once verified, set `SMTP_FROM_ADDRESS` to an address on that domain.
+
+> **WARNING:** SendGrid rejects mail from senders it cannot verify. Authenticating the whole domain is the right choice for a store, because every address on it can then send. Single Sender Verification exists for one-off addresses, but it does not scale to a store's From, reply-to and notification addresses.
+
+## Account plans
+
+SendGrid **retired its free plans in 2025**. New accounts now start on a 60-day trial that allows up to 100 emails per day, and when the trial ends any integration using the account's API keys stops sending until you move to a paid plan. Plan for a paid plan before launch rather than discovering the cutoff when order confirmations stop.
+
+## Related
+
+- [Emails](../../developer/providers/emails.md) — the SMTP variables and how to verify delivery
+- [Sending out Emails](../../developer/deployment/emails.md) — what Spree sends and when
+- [SendGrid SMTP documentation](https://www.twilio.com/docs/sendgrid/for-developers/sending-email/getting-started-smtp)

package/dist/integrations/integrations.md

@@ -39,6 +39,18 @@ Paying sellers, rather than taking money from shoppers. See [Seller payouts](../
   - [Meilisearch](search/meilisearch.md) — One platform to build, scale, and unify search and AI retrieval. Search-as-you-type returns answers in less than 50 milliseconds. That's faster than the blink of an eye!
 
 
+## Emails
+
+Spree sends transactional email over plain SMTP, so any provider works with the same environment variables. See [Emails](../developer/providers/emails.md) for the configuration and how to choose between them.
+
+
+  - [Resend](email/resend.md) — Developer-focused transactional email with a fast setup — add a domain, create an API key, and send.
+  - [Postmark](email/postmark.md) — Built specifically for transactional email, keeping order and account mail apart from bulk sending.
+  - [SendGrid](email/sendgrid.md) — A long-established platform for high volume, with detailed analytics and deliverability tooling.
+  - [Mailgun](email/mailgun.md) — Flexible routing with a choice of US or EU infrastructure for stores that keep email data in Europe.
+  - [Amazon SES](email/amazon-ses.md) — The cheapest option at volume, and the natural fit for a store already running on AWS.
+
+
 ## Analytics
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.268",
+  "version": "0.1.270",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",