How to use macros in templates

In Shared Email Templates for Outlook

Using the Shared Email Templates macros, you can easily avoid repetitive actions and automatically attach files, insert pictures, and fill in the Bcc, Cc, or Subject field in your emails. You can also add dynamic content, dropdown lists, and fillable fields to your templates.

On this page, you'll find instructions on how to use macros.

Note. A maximum of one nested level of macros is supported: ~%Macro1{~%Macro2{}}

To download a quick How to use macros cheat sheet, click the button below:
Download cheat sheet

How to add a macro to your template

To add a macro, take the following steps:

  1. Select an existing template or create a new one and click Edit:
    Start editing a template.
  2. In the text of the template, place the cursor where you want to put a macro and click the Insert macro icon:
    Here is the Insert macro icon.
  3. In the Search box, type words that will help you find the necessary macro. For example, if you want the full name of the recipient to be inserted into the message body, type "full name" in the Search box and double-click Insert Recipient Full Name in the list you'll see or select Insert Recipient Full Name and click Select:
    Select a macro.

The macro is inserted. It's shown in the text of the template with a macro placeholder:
This is a template with the inserted macro.

Tip. If you want to see the formatting applied to a macro placeholder right in the text of your template, change the Default macros style to the Dashed one.

Every time you paste the template into your email message, the full name of the recipient will be inserted automatically.

What macros do and how to use them

Try out all the macros to discover how to simplify your email routine with them.

Fill in email fields: To, Cc, Bcc, Subject

To put some email addresses or text into email fields, you can use the ~%Fill macro or the ~%Add macro.

Note. It doesn't matter where in the text of a template you insert the ~%Fill and ~%Add macros. They don't show up in the message body.
  • You can insert the necessary email addresses (separated by semicolons) into the To, Cc, and Bcc fields with the ~%Fill macro. Any email addresses that were added previously will be deleted.
  • The ~%Fill macro can also help you fill in the Subject field with the text you need. The text that was added to the Subject field previously will be deleted.
  • If you want to add some email addresses (separated by semicolons) to the To, Cc, and Bcc fields, the ~%Add macro will be helpful. All the email addresses added previously will be kept.
  • With the ~%Add macro, you can also add the necessary text to the Subject field. The text you already have there will be kept.

    By default, the text added by the ~%Add macro is inserted after the text that is already in the Subject field. If you want the text of interest to be added to the beginning of the Subject, select the Before checkbox when inserting the macro:
    Make sure this checkbox is selected.

Attach files to emails

Attach files from OneDrive, SharePoint, or a URL with the ~%Attach macro. Or, use the ~%WhatToAttach macro as a reminder. Here is the detailed guide: How to attach files to your templates

Insert images into the message body

To insert images from OneDrive, SharePoint, or a URL, use the ~%InsertPicture macro. For more information, visit the How to insert pictures into your templates page.

Add information to the message body

Add subject, date, time

If you want to insert the Subject field contents into the message body, use the ~%Insert macro. This macro can also help you add the current date and current time to your email message.

Add addresses from the To, Cc, and Bcc fields

Use the ~%Insert macro to insert the contents of the To, Cc, or Bcc field into the message body.

Insert the recipient and sender names

You can insert the first, full, or last name of the recipient or the sender into the message body with the ~%Insert macro.

Note. If the name of the recipient isn't displayed in the To field, the macro will insert the recipient's email address instead.
Note. The ~%Insert macro may not work in some cases because of Outlook bugs.

Paste mailbox, profile, and team properties

Easily add mailbox, profile, and team properties to your templates with the ~%Insert macro. Here is the How to use team, profile, mailbox properties guide.

Add a value from a dataset

Use the ~%DatasetValue macro to add a fixed value from a dataset. Here is the manual.

Enter text or pick a date with the ~%WhatToEnter macro

To explore all the possibilities the ~%WhatToEnter macro offers, visit this help page:
Create templates with fillable fields, dropdown lists, etc.

Clear the message body and disable pasting a template

The ~%Clear macro will help you clear the message body as well as the To, Cc, Bcc, and Subject fields.

With the ~%DisableIf macro, a template won't be pasted if the condition that you specified is met.

Add an internal note to a template

To leave an internal note in a template for yourself or your teammates, use the ~%Note macro. It will be present only in the template itself and won't change an email message.

In the template preview mode, the macro placeholder looks like this:

A closed note in the preview

To see the text of a note, simply hover the cursor over the macro placeholder. To open the note, click the macro placeholder:
An opened note in the preview

If you want notes to open automatically, choose one of the two following ways:

  • When inserting the ~%Note macro into a template, select the Auto expand checkbox in the macro dialog:
    Make sure this checkbox is selected.

    As a result, such a note will open automatically.

  • Add the AutoExpandNoteMacros property with the "true" value to your profile or team properties:
    Adding the AutoExpandNoteMacros property

    As a result, all the notes you have in your templates will open automatically for your profile or for your team(s).

Create meetings and appointments in the Outlook Calendar

You can create appointments and schedule meetings with the help of templates and use the ~%Fill, ~%Add, and ~%Insert macros in them. Detailed information is available on the Use Shared Email Templates in Outlook Calendar page.

Add merge fields

To personalize templates for mail merge campaigns, use the ~%MergeField macro. Here is the step-by-step guide.

Nested macros

Note. You can use nested macros as long as they don't exceed one nested level.

If you want to combine two macros making them work together for you, just nest one of them in the other.

Suppose you would like not only to automatically fill in the Subject line with some text but also to have the opportunity to change this text if necessary. In this case, you'll need to nest the ~%WhatToEnter macro in the ~%Fill macro:

  1. Select Fill Subject and click the Insert Macro button in the dialog window that will appear.
    Nest a macro.
  2. Select What to Enter, fill in the fields that the dialog window of the macro to be nested contains, and then click Insert.
    Select the macro to be nested.

This is an example of how the HTML code will look like:

~%Fill{"field":"subject","value":"~%WhatToEnter{\"type\":\"text\",\"title\":\"Text for Subject line\",\"defaultValue\":\"A very important reminder\",\"required\":false}"}

When you paste a template containing such HTML code into your email message, you'll see a dialog window showing the text for the Subject line. You can always change this text if you want to.
You can type some other text if needed.

The complete list of macros

For a detailed description of each macro, including syntax and examples of use, refer to the Complete list of macros.


Lawson Jones says:
April 6, 2022 at 5:54 pm

Hi, is there I can enter some of my ~%WhatToEnter into the Subject? For example, some of my fillable fields include the date of an event and the event name. I would like those to automatically appear in the subject as well.

Can I format a date? or even display just a part like DATE(MONTH) ?

Hello Cristian,

Thank you for your questions.

If I understand your request correctly, please try to use the ~%WhatToEnter macro that allows you to pick a date in the calendar when inserting a template into a message. You can also set a certain format and language for your dates. For more details, please see this guide:

If it is not exactly what you need, then please clarify your request.

Vignas Gunasegaran says:
February 15, 2021 at 4:25 pm

I have unique links that I send a lot, I would l like the hyperlink to be "click me" style but is there a quick way to get that added in when i start the snippit via what to enter?


I just cannot get the results from the ~%WHAT_TO_ENTER[] macro you posted above here.
The syntax of Pick Date ist unclear as well as I do not get the result even when trying to copy your examples here.I still get the Question Box (which does look different then yours given here) and everything is an item from the dropdown list, that's it.
Can you please provide the full syntax and potential options ?

Hello Lars,

Thank you for your comment. Sorry to hear that the instructions above are not clear for you.

If you'd like to insert a date into a certain place in your message using the ~%WHAT_TO_ENTER[] macro, please do the following:

- Click the New button at the bottom of the add-in pane to create a new template.
- Type in the template text and put the cursor where you'd like to insert a date. Then open the Insert Macro drop-down and choose ~%WHAT_TO_ENTER[] from the list.
- You will see the What To Enter dialog window with three fields. Click on the down arrow in the top field and select "Date".
- Enter the title for the window that will appear when inserting the template, for example, "Due date".
- Then click Insert, the macro will look as follows: ~%WHAT_TO_ENTER[{date,title:"Due date"}].
- Save the template and try to insert it into the email. When you do this, you will see the dialog box called "Due date" with the current date. You can click on the down arrow in the date field to open the calendar and pick another date.

If your case is different, then please explain in detail what you'd like to do and we'll help you with creating a necessary macro. Feel free to email us at for further assistance.

Hello, is it possible to get multi-line text as WHAT_TO_ENTER value?

Hello Giuseppe,

Thank you for your question. I have just replied to your query by email. Please check your Inbox.

Kelvin Niss says:
May 8, 2020 at 3:59 pm

I'm trying to use the WHAT_TO_ENTER to have it in a drop-down list, however it always appears to me like the last example, an empty box to type the information. Is there anything i can do to have it in a list?

Hello Kelvin,

If you want to have a drop-down list to be displayed when inserting the ~%WHAT_TO_ENTER[] macro, you should enter list items through a semicolon in the square brackets next to the macro name like in the example above, ~%WHAT_TO_ENTER[Item 1; Item 2; Item 3].

If you mean something different, then please send us the HTML code of your template for checking. Simply select the template you're having difficulties with and hit Edit. Then, find and click the icon to open the View HTML pane. Select all the text you see in the HTML window, copy it, paste in a Word document and send it to We'll try to help.

There are times where I want to use ~%WHAT_TO_ENTER[] to get some information and then use it again later, but I don't want to have to ask again. Can you consider adding the ability to store and access variables? Something like ~%SAVE_TO_VARIABLE[1, Prompt Message] and ~%USE_VARIABLE[1]. You could use indexes to reference which variable to save and use and limit a template to say 10, 20, or whatever number makes sense.


Hello Michael,

I have just replied to your query by email. Please provide us with the information requested in the email so that we'll be able to help you better. Thank you.

Same question.
Typically I want to use a ~%WHAT_TO_ENTER[] entry into body message AND into Subject field without typing twice.


Post a comment

Seen by everyone, do not publish license keys and sensitive personal info!

If you have any questions or issues with this add-in, please feel free to post your concerns in the comments area. As soon as we answer, a notification message will be sent to your e-mail. If you do not want to share your thoughts in public, please contact us at