- 5 Minutes to read
- Print
- DarkLight
Add an Individual Attachment to a Message
- 5 Minutes to read
- Print
- DarkLight
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).
Mapp Engage does not check your attachments or run a virus scan on them. You are responsible to ensure that the external source of the attachments is secure and can be trusted.
During processing, each attachment generates a single request to the web server on which the attachments are stored. The web server that stores the attachments must therefore be able to handle the number of requests that arise during processing. Sendout speed and other factors can affect server load.
Procedure
The procedure requires several steps.
Insert the Mapp Engage Variable
Adapt the Mapp Engage Variable for Individual Attachments
Customize the Variable for Stable URL Paths
Customize the Variable for a URL with Query Strings
Send a Notification When the Attachment Is Missing
Insert the Mapp Engage Variable
Create an email message.
Click the Mapp Engage Variables button.
From the Category drop-down list, select Content Block.
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
Insert the Mapp Engage Variable into your email.
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'>.