Email Template Variables

Reference documentation for all available template variables, organized by template type. Required variables are marked with Required.

---

Common Variables (Auto-Injected)

These variables are automatically injected when brokerage_id is provided to the render function:

Variable	Type	Description
brokerage_name	string	Brokerage display name from database
brokerage_logo_url	url	Brokerage logo URL, or HomeStar fallback

Note

You can still pass these explicitly to override the auto-injected values.

---

Platform Templates

verification

Sent when a broker registers to verify their email address.

Variable	Required	Type	Description
brokerage_name	Yes	string	Name of the registering brokerage
broker_name	Yes	string	Name of the person registering
verification_url	Yes	url	Full URL for email verification

Example usage:

render_template(
    "verification",
    brokerage_name="Coastal Properties",
    broker_name="Dana Shore",
    verification_url="https://homestar.ink/verify?token=abc123"
)

---

magic_link

Passwordless login link for favorites sync functionality.

Variable	Required	Type	Description
verify_url	Yes	url	Magic link URL for authentication
brokerage_name	Yes	string	Brokerage name for branding
expiry_minutes	No	integer	Link expiration time (default: 15)

Example usage:

render_template(
    "magic_link",
    verify_url="https://app.homestar.ink/auth/magic?token=xyz",
    brokerage_name="Mountain View Realty",
    expiry_minutes=30
)

---

lead_assignment

Notifies agents when a lead is assigned or reassigned to them.

Variable	Required	Type	Description
agent_name	Yes	string	Receiving agent’s display name
lead_name	Yes	string	Lead’s full name
lead_email	Yes	string	Lead’s email address
lead_phone	Yes	string	Lead’s phone (or italic “Not provided”)
subject_type	Yes	string	Type of inquiry (buying, selling, etc.)
message_preview	Yes	string	First 200 chars of lead’s message
dashboard_url	Yes	url	Link to lead in admin dashboard
header_title	Yes	string	“New Lead Assigned” or “Lead Reassigned”
action	Yes	string	“assigned” or “reassigned from {name}”
footer_message	Yes	string	Context about the assignment

Example usage:

render_template(
    "lead_assignment",
    agent_name="Sarah Chen",
    lead_name="John Smith",
    lead_email="john@example.com",
    lead_phone="(208) 555-1234",
    subject_type="Buying",
    message_preview="I'm looking for a 3-bed home...",
    dashboard_url="https://app.homestar.ink/admin/leads/42",
    header_title="New Lead Assigned",
    action="assigned",
    footer_message="This lead was automatically routed to you."
)

---

Customizable Templates

lead_notification

Alerts agents about new lead inquiries from the website.

Variable	Required	Type	Description
agent_name	Yes	string	Receiving agent’s name
lead_name	Yes	string	Lead’s full name
lead_email	Yes	string	Lead’s email address
lead_phone	Yes	string	Lead’s phone (or italic “Not provided”)
subject_type	Yes	string	Type of inquiry (buying, selling, renting, etc.)
message	Yes	string	Lead’s full message
dashboard_url	Yes	url	Link to lead in admin dashboard
property_section	No	html	Optional MJML section with property details
brokerage_name	Yes	string	Brokerage name (auto-injected)
brokerage_logo_url	Yes	url	Brokerage logo (auto-injected)

Example usage:

render_lead_notification_email(
    agent_name="Mike Rodriguez",
    lead_name="Emma Wilson",
    lead_email="emma@example.com",
    lead_phone="(208) 555-9876",
    subject_type="buying",
    message="I'm interested in scheduling a viewing...",
    dashboard_url="https://app.homestar.ink/admin/leads/55",
    property_address="456 Pine Avenue, Boise, ID",
    brokerage_id=3
)

---

tour_confirmation

Confirms a scheduled property tour with the client.

Variable	Required	Type	Description
client_name	Yes	string	Client’s display name
property_address	Yes	string	Full address of tour property
tour_date	Yes	string	Formatted date (e.g., “Saturday, January 25”)
tour_time	Yes	string	Formatted time (e.g., “2:00 PM”)
agent_name	Yes	string	Conducting agent’s name
agent_phone_display	No	html	Agent phone with tel: link formatting
brokerage_name	Yes	string	Brokerage name (auto-injected)
brokerage_logo_url	Yes	url	Brokerage logo (auto-injected)

Example usage:

render_tour_confirmation_email(
    client_name="Robert Taylor",
    property_address="789 Oak Street, Eagle, ID 83616",
    tour_date="Saturday, January 25",
    tour_time="2:00 PM",
    agent_name="Lisa Park",
    agent_phone="(208) 555-4321",
    brokerage_id=5
)

Note

The agent_phone parameter is automatically formatted into agent_phone_display with proper HTML tel: link.

---

market_report

Delivers downloadable market reports to prospects.

Variable	Required	Type	Description
greeting	No	string	Personalized greeting (default: “Hi there!”)
area_display	Yes	string	Market area name (e.g., “Boise, Idaho”)
download_url	Yes	url	URL to download the PDF report
unsubscribe_url	Yes	url	URL to unsubscribe from reports
brokerage_name	Yes	string	Brokerage name (auto-injected)
brokerage_logo_url	Yes	url	Brokerage logo (auto-injected)

Example usage:

render_market_report_email(
    area_display="Boise, Idaho",
    download_url="https://cdn.homestar.ink/reports/boise-jan-2025.pdf",
    brokerage_name="HomeStar Realty",
    unsubscribe_url="https://homestar.ink/unsubscribe?token=abc",
    name="Jennifer",  # Optional - creates "Hi Jennifer!"
    brokerage_id=1
)

---

Variable Categories in Editor

The visual editor groups variables by semantic category based on naming prefixes:

Prefix	Category	Examples
client_, recipient_, user_	Recipient	client_name
property_, listing_	Property	property_address
agent_	Agent	agent_name, agent_phone_display
brokerage_, broker_	Brokerage	brokerage_name, brokerage_logo_url
tour_	Tour	tour_date, tour_time
lead_	Lead	lead_name, lead_email
market_, report_	Market	area_display

Variables not matching these prefixes appear in the Other category.

---

Variable Badge Colors

In the editor’s Variables panel:

Badge Color	Meaning
Amber	Required variable - must be provided
Gray	Optional variable - may be empty

Caution

Missing required variables will render as literal {variable_name} in sent emails. Always verify all required variables are populated.

---

HTML in Variables

Some variables accept HTML content:

Variable	HTML Usage
agent_phone_display	Line break and tel: link for phone
property_section	Full MJML section for property details
lead_phone	Italic “Not provided” fallback

Caution

Keep HTML simple and email-safe. Complex HTML may not render correctly across all email clients.

---

Default Values

Some templates have sensible defaults:

Template	Variable	Default
magic_link	expiry_minutes	15
market_report	greeting	"Hi there!"
lead_notification	property_section	"" (empty)

---

Convenience Functions

The backend provides type-safe convenience functions for each template:

# Instead of raw render_template()
from idx_api.services.email_templates import (
    render_verification_email,
    render_magic_link_email,
    render_lead_notification_email,
    render_lead_assignment_email,
    render_tour_confirmation_email,
    render_market_report_email,
)

These functions:

• Enforce required parameters at the function signature level
• Handle variable formatting (phone numbers, HTML sections)
• Accept brokerage_id for auto-injection
• Return compiled HTML ready for sending

---

Related Documentation

• Manage Email Templates — How to edit templates
• Email Template Architecture — How the system works