> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Save an email template draft
> Saves the draft, in any state; customers keep receiving the published
version until it is published. Send the `lock_version` the draft was
loaded with: a save made from an older copy is refused with 409,
naming who saved last. The first save starts from what is published,
else Spree's default.
**Required scope:** `write_email_templates` (for API-key authentication).
## OpenAPI
````yaml /api-reference/admin.yaml put /api/v3/admin/email_templates/{email_template_id}/draft
openapi: 3.0.3
info:
title: Admin API
contact:
name: Spree Commerce
url: https://spreecommerce.org
email: hello@spreecommerce.org
description: >
Spree Admin API v3 - Administrative API for managing products, orders, and
store settings.
## Authentication
The Admin API requires a secret API key passed in the `x-spree-api-key`
header.
Secret API keys can be generated in the Spree admin dashboard.
## Response Format
All responses are JSON. List endpoints return paginated responses with
`data` and `meta` keys.
Single resource endpoints return a flat JSON object.
## Resource IDs
Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,
`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,
request bodies, and Ransack filters all accept them directly.
## Error Handling
Errors return a consistent format:
```json
{
"error": {
"code": "validation_error",
"message": "Validation failed",
"details": { "name": ["can't be blank"] }
}
}
```
version: v3
servers:
- url: http://{defaultHost}
variables:
defaultHost:
default: localhost:3000
security: []
tags:
- name: Authentication
description: Admin user login, logout, token refresh, and current user profile
- name: Allowed Origins
description: CORS allowlist for storefront and admin client origins
- name: API Keys
description: Secret and publishable API keys
- name: Categories
description: >-
Hierarchical product categories — tree management, repositioning, and
product assignments
- name: Channels
description: >-
Sales channels, product publication across channels, and per-channel order
routing rules
- name: Custom Fields
description: >-
Custom field definitions for products, variants, customers, and other
resources
- name: Customer Groups
description: >-
Customer groups for segmenting customers (e.g. wholesale, VIP) used by
pricing and promotions
- name: Customers
description: Customer profiles, addresses, credit cards, and store credits
- name: Email Templates
description: >-
Customer email templates, the email layout and shared partials: drafts,
previews, publishing and history
- name: Exports
description: Async CSV exports of admin resources
- name: Files
description: Uploading the files that product media, imports, logos and documents use
- name: Fulfillments
description: Order fulfillments — shipments, fulfill, cancel, resume, split
- name: Gift Cards
description: Gift cards and gift card batches
- name: Imports
description: >-
Async CSV imports of admin resources, with per-row status and failed-row
retry
- name: Markets
description: >-
Markets — geographic groupings of countries used for pricing, tax, and
fulfillment rules
- name: Option Types
description: >-
Option types and option values used to build product variants (e.g. Size,
Color)
- name: Orders
description: Orders, order items, applied gift cards, and applied store credits
- name: Payment Methods
description: Configured payment providers and their available types
- name: Payments
description: Order payments — list, capture, void
- name: Pricing
description: >-
Prices and price lists for currency-, market-, and customer-group-specific
pricing
- name: Products
description: >-
Products, taxons/categories, product custom field values, and bulk product
operations
- name: Policies
description: The store's legal documents — terms of service, privacy, returns, shipping
- name: Reasons
description: >-
Merchant-owned vocabularies for why a return, claim, refund, cancellation
or tax exemption happened
- name: Promotions
description: Promotions, promotion rules, promotion actions, and coupon codes
- name: Refunds
description: Order refunds
- name: Settings
description: Store-level settings — store profile, tags, and configuration
- name: Staff
description: Admin users, roles, and invitations to the store
- name: Stock Locations
description: Warehouses and physical fulfillment locations
- name: Store Credits
description: Prepaid customer balances across all customers, and each balance's ledger
- name: Variants
description: >-
Product variants — the individual SKUs (size/color combinations) sold
under a product
- name: Webhooks
description: Webhook endpoints and webhook delivery history
paths:
/api/v3/admin/email_templates/{email_template_id}/draft:
parameters:
- name: email_template_id
in: path
required: true
description: The template key with dots
schema:
type: string
put:
tags:
- Email Templates
summary: Save an email template draft
description: >-
Saves the draft, in any state; customers keep receiving the published
version until it is published. Send the `lock_version` the draft was
loaded with: a save made from an older copy is refused with 409,
naming who saved last. The first save starts from what is published,
else Spree's default.
**Required scope:** `write_email_templates` (for API-key
authentication).
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- name: Authorization
in: header
required: true
description: Bearer token for admin authentication
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmailTemplateDraftParams'
required: true
responses:
'200':
description: draft saved
content:
application/json:
example:
id: spree.order_mailer.confirm_email
key: spree/order_mailer/confirm_email
subject: Order {{ order.number }} confirmed
body: >
Thanks for your order, {{
order.customer_name }}!
language: any
customized_languages: []
kind: email
customized: false
published_at: null
default_subject: Order {{ order.number }} confirmed
default_body: >
Thanks for your order, {{
order.customer_name }}!
published_language: null
default_changed: false
base_subject: null
base_body: null
draft:
id: etdr_UkLWZg9DAJ
subject: Your order {{ order.number }} is confirmed
body: >-
Thanks, {{
order.customer_name }}!
lock_version: 0
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
updated_by_id: adm_UkLWZg9DAJ
updated_by_type: admin_user
schema:
$ref: '#/components/schemas/EmailTemplate'
'409':
description: saved by someone else since it was loaded
content:
application/json:
example:
error:
code: email_template_stale
message: >-
Mirta Hamill saved this draft after you opened it. Reload to
see their changes before saving yours.
details:
updated_by: Mirta Hamill
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- api_key: []
bearer_auth: []
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
source: >-
import { createAdminClient } from '@spree/admin-sdk'
const client = createAdminClient({
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
// Pass the lock_version the draft was loaded with: a save made from
an
// older copy is refused with 409, naming who saved last.
const template = await
client.emailTemplates.draft.update('spree.order_mailer.confirm_email',
{
subject: 'Your order {{ order.number }} is confirmed',
body: 'Thanks, {{ order.customer_name }}!',
lock_version: 0,
})
- lang: bash
label: Spree CLI
source: >-
spree api put /email_templates/{email_template_id}/draft -d
'{"subject":"Your order {{ order.number }} is
confirmed","body":"Thanks, {{
order.customer_name
}}!","lock_version":0}'
components:
schemas:
EmailTemplateDraftParams:
type: object
properties:
language:
type: string
description: >-
A language code, or `any` (the default) for the version every
language uses.
example: any
subject:
type: string
example: Your order {{ order.number }} is confirmed
nullable: true
body:
type: string
example: >-
Thanks, {{ order.customer_name
}}!
lock_version:
type: integer
description: >-
The `lock_version` the draft was loaded with, or null when there was
no draft; a save from an older copy is refused with 409. Omit it to
save without checking.
example: 0
nullable: true
rebase:
type: boolean
description: >-
Marks the draft as based on Spree's current default, after reviewing
what changed in it.
EmailTemplate:
type: object
properties:
id:
type: string
key:
type: string
subject:
type: string
nullable: true
body:
type: string
language:
type: string
customized_languages:
type: array
items:
type: string
kind:
type: string
enum:
- email
- layout
- partial
customized:
type: boolean
published_at:
type: string
nullable: true
default_subject:
type: string
nullable: true
default_body:
type: string
published_language:
type: string
nullable: true
default_changed:
type: boolean
base_subject:
type: string
nullable: true
base_body:
type: string
nullable: true
draft:
allOf:
- $ref: '#/components/schemas/EmailTemplateDraft'
nullable: true
required:
- id
- key
- subject
- body
- language
- customized_languages
- kind
- customized
- published_at
- default_subject
- default_body
- published_language
- default_changed
- base_subject
- base_body
- draft
x-typelizer: true
ErrorResponse:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: record_not_found
message:
type: string
example: Record not found
details:
type: object
description: Field-specific validation errors
nullable: true
example:
name:
- is too short
- is required
email:
- is invalid
required:
- code
- message
required:
- error
example:
error:
code: validation_error
message: Validation failed
details:
name:
- is too short
email:
- is invalid
EmailTemplateDraft:
type: object
properties:
id:
type: string
subject:
type: string
nullable: true
body:
type: string
lock_version:
type: number
created_at:
type: string
updated_at:
type: string
updated_by_id:
type: string
nullable: true
updated_by_type:
anyOf:
- type: string
enum:
- admin_user
- api_key
- type: string
nullable: true
description: The values listed are the built-in ones; extensions may add more.
updated_by:
$ref: '#/components/schemas/Actor'
required:
- id
- subject
- body
- lock_version
- created_at
- updated_at
- updated_by_id
- updated_by_type
x-typelizer: true
Actor:
type: object
properties:
id:
type: string
type:
anyOf:
- type: string
enum:
- admin_user
- api_key
- type: string
description: The values listed are the built-in ones; extensions may add more.
label:
type: string
nullable: true
required:
- id
- type
- label
x-typelizer: true
securitySchemes:
api_key:
type: apiKey
name: x-spree-api-key
in: header
description: Secret API key for admin access
bearer_auth:
type: http
scheme: bearer
bearerFormat: JWT
description: JWT token for admin user authentication
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.