Email design

Brand defaults for your workspace, a design.md file agents can edit, variables with fallbacks, and a block document that renders to inline-CSS HTML and plain text.

Brand defaults

Set them in Settings, Email design, or over the API with GET and PUT /v1/email-design. Only owners, admins and full scope API keys can change them.

Field	Value	Used for
color	hex, default #0007cd	Buttons and links in Designed email.
font	sans \| serif \| mono	Email safe font stacks.
align	left \| center	Text alignment in Designed email.
logo_url	https URL	Shown at the top of Designed email.
header_text	up to 500 characters	Shown at the top when there is no logo.
footer_text	up to 500 characters	Printed in the footer block.
address	up to 300 characters	Physical postal address, required for marketing email (CAN-SPAM).

When the brand has no address, the footer uses the workspace sender address from Settings, Sender address. Without either, a footer with an unsubscribe link fails with missing_address.

design.md

The same settings as a small markdown file. Pull it, edit it, push it back.

---
color: "#0007cd"
font: sans
align: left
logo: https://acme.com/logo.png
---

# Email design

## Header
Acme

## Footer
You get this because you signed up.

## Address
1 Main St
Austin, TX 78701

Front matter keys are color, font, align and logo. Sections are ## Header, ## Footer and ## Address. Anything else is an invalid_design_md error that says what to change.

# CLI
runearc email-design pull --out design.md
runearc email-design push design.md

# REST
curl https://api.runearc.com/v1/email-design/design.md \
  -H "Authorization: Bearer $RUNEARC_API_KEY"
curl -X PUT https://api.runearc.com/v1/email-design/design.md \
  -H "Authorization: Bearer $RUNEARC_API_KEY" \
  -H "Content-Type: text/markdown" --data-binary @design.md

# MCP tools: get_email_design, set_email_design

Write {{NAME}} or {{NAME|fallback}} anywhere in a subject, text, heading, button or row. Names are capital letters, digits and underscores, starting with a letter. Values are HTML escaped. A blank value uses the fallback. A name with no value and no fallback fails with unknown_variable and a fix that suggests a fallback.

The email document

{
  "version": 1,
  "style": "designed",
  "subject": "Welcome, {{FIRST_NAME|there}}",
  "preheader": "Here is how to start",
  "blocks": [
    {"type": "heading", "text": "Welcome", "level": 1},
    {"type": "text", "text": "Hi {{FIRST_NAME|Friend}}.\n\nRead the **docs**: [open](https://example.com/docs)"},
    {"type": "button", "label": "Get started", "url": "https://example.com/start"},
    {"type": "image", "src": "https://example.com/a.png", "alt": "Product", "href": null},
    {"type": "divider"},
    {"type": "rows", "rows": [["Plan", "Pro"], ["Total", "{{AMOUNT|$0.00}}"]]},
    {"type": "code", "code": "{{CODE}}"},
    {"type": "footer", "unsubscribe": true}
  ]
}

style is designed (card, logo, brand color) or plain (no chrome). At most 50 blocks. Links must be https://, http:// or mailto:; image sources must be http or https. A footer with unsubscribe: true needs the UNSUBSCRIBE_URL variable and a postal address.

Preview a render

curl -X POST https://api.runearc.com/v1/email-design/render \
  -H "Authorization: Bearer $RUNEARC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document": {...}, "vars": {"FIRST_NAME": "Ana"}}'
# { "subject": "...", "html": "...", "text": "..." }

# CLI
runearc email-design preview doc.json --var FIRST_NAME=Ana
# MCP tool: render_email_preview

Brand defaults#

design.md#

Variables#

The email document#

Preview a render#

Brand defaults

design.md

Variables

The email document

Preview a render