Add an Individual Attachment to a Message

Goal

To send a different attachment to each email recipient. The attachments are stored on a server and attached to each email during the sendout process.

You do not need to use this variable to send the same attachment to all email recipients. You can upload a single attachment in the ​Advanced Options​ area when you create an email message.

Background Information​

This Mapp Engage Variable enables you to send a different attachment to each email recipient. For example, you can use this variable to send invoices or account statements. To add the attachment, drag and drop the variable into the email message. During sendout, Mapp Engage retrieves the attachment for each contact from the specified server and attaches the file to the email. Each contact receives the correct file.

You must store the personalised attachments on a separate web server. You cannot upload the personalised attachments from your local computer. To secure the data, access can be limited to certain IP addresses (IP restriction).

Procedure

The procedure requires several steps.

1. Insert the Mapp Engage Variable​

2. Adapt the Mapp Engage Variable for Individual Attachments​

   1. Customize the Variable for Stable URL Paths​

   2. Customize the Variable for a URL with Query Strings​

3. Send a Notification When the Attachment Is Missing​

Insert the Mapp Engage Variable​

1. Create an email message.
2. Click the ​Mapp Engage Variables​ button.
3. From the ​Category​ drop-down list, select ​Content Block​.
4. Drag and drop the ​Individual Attachment​ variable into the email message. The location of the variable in the email does not matter.
   When you add the variable to the email, the variable has the following format:
   <ecm:attach xmlns:ecm=''URL'http://domain.com/mail'><ecm:url>'URL'</ecm:url></ecm:attach>

Adapt the Mapp Engage Variable for Individual Attachments​

The ​Individual Attachment​ variable contains various commands that identify the location and name of the file.
After you add the variable to the email, you must specify the URL. The correct format of the URL depends on whether the files are stored at a stable URL, or at a URL with query strings.

Do not change any other part of the variable.

• Customize the Variable for Stable URL Paths​

• Customize the Variable for a URL with Query Strings​

Because you are attaching a different file for each contact, a part of the path or the file name is unique for each contact. The data that you use to create the unique file name must be stored in Mapp Engage in a standard or custom profile value. When you customize the Mapp Engage Variable, you use the ecm: command to indicate how this unique path or file name is constructed. The ecm: command includes the attribute reference of the Mapp Engage attribute.

Example

The file name consists of value that is stored in the Mapp Engage standard attribute user.lastname for the contact.

• The Mapp Engage Variable must contain the following command: <ecm:user.lastname/>.pdf

Example

The file name consists of the value that is stored in the Mapp Engage custom attribute user.CustomAttribute.CustomerID for the contact.

• The Mapp Engage Variable must contain the following command: <ecm:user.CustomAttribute.CustomerID/>.pdf

For a list of attribute references, see Attribute References​. Do not use % % characters in the ecm: command in the Mapp Engage Variable.

If the specified URL does not contain any files, Mapp Engage does not stop message sendout. Mapp Engage sends the message without an attachment.

To send the message only if the attachment is available, add the value required='true' to the <ecm:attach> command.

Customize the Variable for Stable URL Paths​

An address with a stable URL path and a personalised file name has the following structure:

• http://host/path/file/<ecm:attribute/>.pdf

The command to attach the individual files has the following format in the email (for example):

• <ecm:attach xmlns:ecm='http://host/path/file/http://domain.com/mail'><ecm:url>http://host/path/file/<ecm:attribute/>.pdf</ecm:url></ecm:attach.pdf>

Explanation

A stable URL address includes the following elements:

• The protocol (http://)

• The URL path (host/path/file/)

• The personalised file name, which is specified with the ecm: command.

Example

Every contact has a folder on the file server. Each file is saved at a dynamic location that references the contact ID, purchase date, and last name of the contact.

The folders are named with the contact ID number. The folder contains the invoices for that contact. The file name for each invoice consists of the purchase date and last name.

The URL of the file server is http://www.mydata.com/emailAttachment/.

• The folders are named with the contact ID number. The customer ID number is stored in the Mapp Engage custom attribute ​CustomerID​. The folder contains the invoices for that contact.

  • The Mapp Engage Variable must contain the following command: <ecm:user.CustomAttribute.CustomerID/>/
    

• The file name consists of the purchase date and last name. The date and time of purchase is stored in the custom attribute user.CustomAttribute.PurchaseDate. The format is YYMMDD. The last name is saved in the standard attribute ​user.lastname​.
  (Example: For a purchase on 15.04.2016 with the last name Jones, the file name of the attachment is ​160415Jones.pdf​.)

  • The Mapp Engage Variable must contain the following command: <ecm:user.CustomAttribute.PurchaseDate/><ecm:user.lastname/>.pdf.

Result

The URL has the following format:

http://www.mydata.com/emailAttachment/1984532325235/160415Jones.pdf

The customized Mapp Engage Variable has the following format:

<ecm:attach xmlns:ecm='http://www.mydata.com/emailAttachment//.pdfhttp://domain.com/mail'><ecm:url>http://www.mydata.com/emailAttachment/<ecm:user.CustomAttribute.CustomerID/>/<ecm:user.CustomAttribute.PurchaseDate/><ecm:user.lastname/>.pdf</ecm:url></ecm:attach>

Customize the Variable for a URL with Query Strings​

In this case, a web application evaluates the address path and the files are transmitted to Mapp Engage via a request. The Mapp Engage Variable must conform to the requirements of the web application.

The query string of a web address begins with a ? (question mark). The character string following the question mark contains commands for the web application. These commands can be personalised using attributes to request the attachments that correspond to each recipient. The structure of the query string must fulfill the requirements of the web application and is independent of Mapp Engage.

The command to attach the individual files has the following format in the email (for example):

<ecm:attach xmlns:ecm='http://host/path/file?parameters=http://domain.com/mail'><ecm:url>http://host/path/file?parameters=<ecm:placeholder/>.pdf</ecm:url></ecm:attach.pdf>

Example

The web application transmits the file that corresponds to the customer ID number and the file name.

The address of the web application is as follows: http://www.mydata.com

The following parameters are expected in the query:

• Customer ID number: UserID=CustomerID. The customer ID number is stored in the Mapp Engage custom attribute ​CustomerID​.

• File name: Filename=PurchaseDateLastname.pdf.
  The file name consists of the purchase date and last name. The date and time of purchase is stored in the custom attribute user.CustomAttribute.PurchaseDate. The format is YYMMDD. The last name is saved in the standard attribute ​user.lastname​.
  (Example: For a purchase on 15.04.2016 with the last name Jones, the file name of the attachment is ​160415Jones.pdf​.)

The customized Mapp Engage Variable has the following format:

<ecm:attach xmlns:ecm='http://ecircle-ag.com/mail'> <ecm:url>http://www.mydata.com?UserID=<ecm:user.CustomAttribute.CustomerID/>&Filename=<ecm:user.CustomAttribute.PurchaseDate/><ecm:user.lastname/>.pdf</ecm:url></ecm:attach>

Special characters in attribute values which are not supported in URL addresses can be converted with URI escape. The special characters are then automatically converted into ASCI values. The conversion command is inserted directly into the placeholder: <ecm:placeholder excape='uri'>. Example: <ecm:user.FirstName escape='uri'/>.

Send a Notification When the Attachment Is Missing​

If the specified URL does not contain any files, Mapp Engage does not stop message sendout. Mapp Engage sends the message without an attachment.

To have Mapp Engage send the message only if the attachment is available, add the value required='true' to the <ecm:attach> command.

You can modify the Mapp Engage Variable to send an email warning message when an attachment is not available.

Procedure

1. Insert the Mapp Engage Variable into your email.
2. To modify the Mapp Engage Variable to send a notification, insert the following code: required='true' alarm-email='email address'
   ⇒  Mapp Engage sends a warning to the email address. The system message which is used for the notification is ​SysMsgAttachmentError​.

Example

You want to send a warning email to the following email address: pdffailed@myaddress.com.

The modified variable has the following format:

<ecm:attach xmlns:ecm='http://ecircle-ag.com/mail' required='true' alarm-email='pdffailed@myaddress.com'>.