Custom Email Template

Magic Staff · April 26, 2024
Custom Email Template

Magic's custom email template feature enables the personalization of email communications sent through a Magic application using unique HTML, colors, and branding. This customization is essential for businesses that want their emails to reflect their brand identity and provide a consistent experience to their end-users.

With the use of Magic’s custom email templates, users can create their HTML email designs directly from the Magic dashboard and integrate them into their Magic application.

This guide will walk you through creating and setting up custom email templates and testing their display and functionality.

#Project prerequisites

To follow along with this guide, you’ll need 4 things:

  1. A Magic Publishable API Key
  2. Subscription to Dedicated Pro Bundle
  3. Custom Email Provider settings configured and enabled
  4. Basic understanding of HTML and CSS

You can get your Publishable API Key from your Magic Dashboard. To subscribe to the Dedicated Pro Bundle please visit the Magic pricing page.

Before you have the ability to create custom email templates, you must have the “Custom Email Provider” feature configured and enabled. Follow along this guide to set that up before you continue on.

#Add Custom Template

We will assume that you have all of the required prerequisites and have created a new application with the "Dedicated Pro Bundle" subscription enabled.

Head over to your Magic Dashboard and select the application from the dropdown menu in the left navigation. Once you've selected the application you want to enable a custom email template with, click on the customization icon and click “Email”.

Next, click the “New Template” button. You will see the customization form and a preview component to the right of it.

There are 3 inputs in the form:

  • Email Type: Select the type of email type you’d like to customize. The two options are “One-Time Passcode” and “Magic Link”.
  • Template Name: The name of the custom template.
  • Subject Line: The subject line you want displayed for your users.

Beneath the inputs from above there is the “Template” component. This is where all of the email body customization happens. As you can see there is already default styling added to this.

#Edit Custom Template

When customizing email templates using HTML and inline CSS, you have the opportunity to design visually appealing and responsive email communications tailored to your specific needs. As you can see in the Template component, there are default styles added. This is where you will add your custom styling and branding for your email template.

The following is a list of variables that can be used when creating a custom email template in Magic. From the dashboard editor, variables must be wrapped in {{}} in order to be resolved to their value. For example, to use the one-time passcode, insert {{otp}} into the template.

  • otp: One-time passcode.
  • magic_link: Magic link URL.
  • The name of the application.
  • Email address of the user receiving the login email.
  • template.locale: Language of the user receiving the login email.
  • login.device.browser: Browser of the user receiving the login email.
  • login.device.os: Operating system of the user receiving the login email.
  • login.timestamp: Timestamp of when email was requested

Add your custom styling to the template. Notice that the preview on the right hand side changes dynamically with every update. At any time you want to test how it looks, click the “Send Test” button.

Once you’re happy with your changes, click “Save and Publish”.

#Test using your own client

We've tested it works from the Magic dashboard, but now we should test it from our own client to ensure that it works correctly. Let's use the Magic CLI tool to scaffold a Next.js app and test our custom email functionality using Email OTP.

Run the following command in your terminal. Replace <YOUR_PUBLISHABLE_API_KEY> with your Magic publishable API key.

01npx make-magic \
02 --template nextjs-dedicated-wallet \
03 --network ethereum-sepolia \
04 --login-methods EmailOTP \
05 --publishable-api-key <YOUR_PUBLISHABLE_API_KEY>

Once you’ve run the command above, change into the project’s directory and navigate to the EmailOTP component in src/components/magic/auth/EmailOTP.tsx.

In your Magic dashboard, select the template you wish to test in your client. Take note of the template name as this is what you will be adding to your code to override the default template.

In the handleLogin function you will see an asynchronous call using loginWithEmailOTP, this is where we will add the override to add our custom email template. Add your template name as the value for variation:

01// Using Email OTP
02const token = await magic?.auth.loginWithEmailOTP(
03  {
04    email,
05    overrides: {
06      variation: 'Your Template Name',
07    }
08  }
11// Using Magic Link
12const token = await magic?.auth.loginWithMagicLink(
13  {
14    email,
15    overrides: {
16      // Add the Template Name from your Magic dashboard
17      variation: 'Your Template Name',
18    }
19  }

Run your local server, head to localhost:3000, and log in with an email address. Check the email you’ve logged in with and make sure that your custom email template is displayed as expected.

Thats it! You’ve just created a custom Magic email template and tested it in your own client.

#Next steps

You now know how to integrate Magic into your project and include the following features:

  1. Simple authentication with Email OTP
  2. Custom email template

Feel free to explore Magic's other email features such as email logs and custom email provider!

Let's make some magic!