How to Customize Appwrite Email Templates in Production | HackerNoon

When running Appwrite in production (especially from Digital Ocean Marketplace or other pre-built installations), you might want to customize email templates to match your brand. This guide shows you how to do it properly using volume mounts to ensure your changes persist across updates.

Understanding Appwrite Email System

Appwrite’s email system consists of two main components:

1. Template Files (.tpl): HTML structure of emails located in /usr/src/code/app/config/locale/templates/
2. Translation Files (.json): Text content for different languages in /usr/src/code/app/config/locale/translations/

Available email templates include:

• email-magic-url.tpl – Passwordless login emails

• email-inner-base.tpl – Password recovery emails

• email-otp.tpl – One-time password emails

• email-mfa-challenge.tpl – Multi-factor authentication

• email-session-alert.tpl – New session notifications

The Problem with Direct Editing

When using pre-built Appwrite images (like from Digital Ocean Marketplace), the files exist inside Docker containers. If you edit them directly in the container, your changes will be lost when you:

• Update Appwrite to a new version

• Recreate containers

• Scale your deployment

The Solution: Volume Mounts

Volume mounts let you replace container files with your own custom versions that persist on the host filesystem.

Step-by-Step Implementation

Step 1: SSH into Your Server

ssh root@your-server-ip 
cd ~/appwrite  # or wherever your docker-compose.yml is located

Step 2: Extract Original Files from Container

Since the files are inside the Docker image, we need to copy them out first:

# Create directories for custom files 
mkdir -p custom-templates 
mkdir -p custom-translations  
# Copy all template files from container 
docker cp appwrite:/usr/src/code/app/config/locale/templates/. ./custom-templates/  
# Copy all translation files from container 
docker cp appwrite:/usr/src/code/app/config/locale/translations/. ./custom-translations/

Important: You must copy ALL translation files, not just the ones you want to edit. When you mount a directory, it replaces the entire directory in the container.

And you should end up like the following:

Step 3: Customize Your Files

Now edit the files you want to customize:

# Edit the English translations 
vim custom-translations/en.json

You insert button, then when finished, insert again, escape then :wq to write and close. Example customization for magic URL email:

{ "emails.magicSession.subject": "Sign In to {{project}}", 
"emails.magicSession.hello": "Welcome back, {{user}}!", 
"emails.magicSession.buttonText": "Access My Account", 
"emails.magicSession.signature": "The {{project}} Team", 
"emails.magicSession.optionButton": "Click below to securely sign in to your {{b}}{{project}}{{/b}} account. This link expires in 1 hour."
 }

Or edit template structure:

vim custom-templates/email-magic-url.tpl

Step 4: Update docker-compose.yml

Add volume mounts to your docker-compose.yml under the appwrite service:

appwrite: 
  image: appwrite/appwrite:1.8.0 
  container_name: appwrite 
  restart: unless-stopped 
  volumes: 
    # Add these two lines for custom email templates 
    - ./custom-templates:/usr/src/code/app/config/locale/templates:ro 
    - ./custom-translations:/usr/src/code/app/config/locale/translations:ro 
    # ... other existing volumes ... - appwrite-uploads:/storage/uploads:rw 
    - appwrite-cache:/storage/cache:rw

The :ro flag makes them read-only for security.

Step 5: Apply Changes

# Recreate the appwrite container with new volumes 
docker compose up -d appwrite
# Restart the mail worker to reload translations
docker restart appwrite-worker-mails

Step 6: Test Your Changes

Trigger a test email through the API:

curl --location 'https://your-domain.com/v1/account/sessions/magic-url'  
--header 'Content-Type: application/json'  
--header 'X-Appwrite-Project: your-project-id'  
--data '{ "userId": "unique()", "email": "[email protected]", "url": "https://your-domain.com/auth" }'

Check your email to see the customized template! Here is the email I received, where you can see the new updates:

Understanding Translation Variables

Translation files use placeholders that get replaced with dynamic values:

• {{project}} – Your project name
• {{user}} – User’s name or email
• {{b}}...{{/b}} – Bold text markers
• {{redirect}} – The action URL
• {{agentClient}} – Browser/client info
• {{agentDevice}} – Device type
• {{agentOs}} – Operating system
• {{phrase}} – Security phrase for verification

Common Email Templates Reference

Magic URL Login

• Template: email-magic-url.tpl
• Translations: emails.magicSession.*
• Triggered by: Creating a magic URL session via API

Password Recovery

• Template: email-inner-base.tpl
• Translations: emails.recovery.*
• Triggered by: Password reset request

Email Verification (OTP)

• Template: email-otp.tpl
• Translations: emails.verification.*
• Triggered by: Email verification flow

Troubleshooting

Changes Not Reflecting

Problem: You updated the files, but emails still show old content.

Solution: Translations are cached in memory. Always restart both containers:

docker restart appwrite 
sleep 5 
docker restart appwrite-worker-mails
# If that still doesn’t work, do a full restart:
docker compose down 
docker compose up -d

Error 500 After Changes

Problem: Server returns 500 error after modifying translation files.

Solution: This usually means JSON syntax error. Validate your JSON:

cat custom-translations/en.json | python3 -m json.tool

Common mistakes:

• Missing commas between properties
• Extra comma after last property
• Using single quotes instead of double quotes
• Unescaped special characters

Missing Translation File Error

Problem: Error saying translation file not found.

Solution: Ensure you copied ALL translation files, not just the ones you modified:

# Re-copy all files 
docker cp appwrite:/usr/src/code/app/config/locale/translations/. ./custom-translations/

Changes Lost After Update

Problem: Updated Appwrite and customizations disappeared.

Solution: This shouldn’t happen with volume mounts. Verify your docker-compose.yml still has the volume mounts after the update.

Development vs Production

Local Development

For local development with the full Appwrite source code:

1. Edit files directly in your local repository
2. Files are already mounted via ./app:/usr/src/code/app
3. Changes are live – just restart containers
4. Test with MailCatcher at http://localhost:9503

Production Deployment

For production:

1. Use the volume mount approach described above
2. Keep your custom files in version control
3. Consider creating a custom Docker image for larger customizations
4. Always test in staging before applying to production

Best Practices

1. Version Control: Keep your custom-templates and custom-translations directories in git
2. Backup: Backup these directories before major updates
3. Testing: Always test email templates in a staging environment first
4. Documentation: Document what you’ve customized for your team
5. Minimal Changes: Only customize what’s necessary – makes updates easier
6. Multi-language: If you support multiple languages, update all relevant translation files