Send a Different Attachment to Each Recipient

Updated
  • 3 minute(s) read
Prev Next

Goal

Attach a different file to each recipient's email, for example an invoice or an account statement. Mapp Engage loads the file for each contact from your web server during sendout.

Note

To attach the same file to all recipients, you do not need this variable. See Add Attachments to an HTML Email.

Background Information

The Individual Attachment variable contains the address of the file. Part of the address is built from a contact attribute, for example the customer ID or the last name. During sendout, Mapp Engage resolves the address for each contact, retrieves the file, and attaches it to the email.

Requirements:

  • The files are stored on a web server. You cannot upload them from your computer.

  • The value that makes the address unique, for example the customer ID, is stored in a standard or custom attribute in Mapp Engage.

  • The web server can handle the load during sendout. Each attachment generates one request to the server. Sendout speed and other factors affect the server load.

To protect the files, you can restrict access to the web server to specific IP addresses.

Warning

Mapp Engage does not check the attachments or scan them for viruses. You are responsible for making sure that the source of the attachments is secure and trusted.

Insert the Variable

  1. Create an email message.

  2. Click Mapp Engage Variables.

  3. From the Category drop-down list, select Content/Attachment.

  4. Drag and drop the Individual Attachment variable into the email. The position of the variable in the email does not matter.

The variable has the following format:

<ecm:attach xmlns:ecm='http://ecircle-ag.com/mail'><ecm:url>'URL'</ecm:url></ecm:attach>

Replace the placeholder 'URL' with the address of the file. Do not change any other part of the variable. How you build the address depends on how your web server provides the files:

  • The files are stored in a fixed folder structure: see Option 1: Stable URL Path.

  • A web application returns the files: see Option 2: URL with Query String.

Build the File Address from Contact Attributes

Because each contact receives a different file, a part of the path or the file name must be unique for each contact. To insert an attribute value into the address, use an ecm: command with the attribute reference:

Attribute

Command

Last name (standard attribute)

<ecm:user.lastname/>

CustomerID (custom attribute)

<ecm:user.CustomAttribute.CustomerID/>

For example, if the file name is the last name of the contact, the address ends with <ecm:user.lastname/>.pdf.

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

Note

If attribute values contain special characters that are not allowed in URLs, add escape='uri' to the command. Mapp Engage then converts the special characters automatically. Example: <ecm:user.FirstName escape='uri'/>

Option 1: Stable URL Path

Use this format if the files are stored in a fixed folder structure and the folder or file name is personalized. The variable has the following structure:

<ecm:attach xmlns:ecm='http://ecircle-ag.com/mail'><ecm:url>http://host/path/file/<ecm:attribute/>.pdf</ecm:url></ecm:attach>

Example

The file server URL is http://www.mydata.com/emailAttachment/. Every contact has a folder on the file server:

  • The folder name is the customer ID. It is stored in the custom attribute CustomerID.

  • The file name consists of the purchase date and the last name. The purchase date is stored in the custom attribute PurchaseDate in the format YYMMDD. The last name is stored in the standard attribute user.lastname.

For a contact with the customer ID 1984532325235 and the last name Jones who made a purchase on 15.04.2016, the file address is:

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

The customized variable has the following format:

<ecm:attach xmlns:ecm='http://ecircle-ag.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>

Option 2: URL with Query String

Use this format if a web application evaluates the address and returns the files. The query string starts with a question mark (?) and contains parameters for the web application. You personalize these parameters with attributes. The structure of the query string depends on the web application, not on Mapp Engage.

The variable has the following structure:

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

Example

The web application at http://www.mydata.com expects two parameters:

  • UserID: the customer ID. It is stored in the custom attribute CustomerID.

  • Filename: the purchase date and the last name, for example 160415Jones.pdf. The purchase date is stored in the custom attribute PurchaseDate in the format YYMMDD. The last name is stored in the standard attribute user.lastname.

The customized 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>

Send Only When the Attachment Is Available

If there is no file at the address, Mapp Engage does not stop the sendout. The message is sent without the attachment.

To send the message only if the attachment is available, add required='true' to the ecm:attach tag:

<ecm:attach xmlns:ecm='http://ecircle-ag.com/mail' required='true'><ecm:url>'URL'</ecm:url></ecm:attach>

To receive a warning email when an attachment is missing, also add alarm-email with the address that receives the warning:

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

Mapp Engage uses the system message SysMsgAttachmentError for the warning.