Mandrill Send Email-Template

This graph allows Xponent to integrate with the Mandrill API - Messages Send-Template endpoint, an email infrastructure service offered as an add-on for MailChimp that you can use to send personalized, one-to-one e-commerce emails. This requires an account with Mandrill.

Email templates are configured in Mandrill (or Mailchimp and exported to Mandrill). These templates can be sent by providing a set of data that feeds into various parameters in the template, such as email address, customer name, product or order number.

This template will call the Mandrill API - Messages Send-Template endpoint and save the action in the interaction and chanEmailMandrill table.

Explaining Mandrill to a client

Mandrill is a transactional email RESTful API for MailChimp users. The API allows emails to be personalized for one-to-one messages. To use Mandrill, the user must use a unique API key found in their Mandrill account, and send a POST request to an endpoint. All methods are accessed via https://mandrillapp.com/api/1.0/SOME-METHOD.OUTPUT_FORMAT. The supported output formats are JSON (default), XML, YAML, and PHP. The official API clients are curl, JSON, python, PHP, ruby, node.js, and dart. The API documentation can be found here.

Package contents

• Graphs: 

• Refresh App Params Graph Template - follow the instructions
• mandrillSendEmailTemplate

• Schema

{
    "interaction": {
        "ts": "",
        "email": {
            "verb": "",
            "header": "",
            "mailId": "",
            "category": "",
            "criteria": "",
            "headline": "",
            "mandrill": {
                "request": {
                    "key": "example key",
                    "async": false,
                    "ip_pool": "Main Pool",
                    "message": {
                        "to": {
                            "0": {
                                "name": "Recipient Name",
                                "type": "to",
                                "email": "recipient.email@example.com"
                            }
                        },
                        "html": "<p>Example HTML content</p>",
                        "tags": "",
                        "text": "Example text content",
                        "merge": true,
                        "images": {
                            "name": "IMAGECID",
                            "type": "image/png",
                            "content": "ZXhhbXBsZSBmaWxl"
                        },
                        "headers": {
                            "Reply-To": "message.reply@example.com"
                        },
                        "subject": "example subject",
                        "metadata": {
                            "website": "www.example.com"
                        },
                        "auto_html": null,
                        "auto_text": null,
                        "from_name": "Example Name",
                        "important": false,
                        "from_email": "message.from_email@example.com",
                        "inline_css": null,
                        "merge_vars": {
                            "rcpt": "recipient.email@example.com",
                            "vars": {
                                "name": "merge2",
                                "content": "merge2 content"
                            }
                        },
                        "subaccount": "customer-123",
                        "attachments": {
                            "name": "myfile.txt",
                            "type": "text/plain",
                            "content": "ZXhhbXBsZSBmaWxl"
                        },
                        "bcc_address": "message.bcc_address@example.com",
                        "track_opens": null,
                        "track_clicks": null,
                        "url_strip_qs": null,
                        "merge_language": "mailchimp",
                        "signing_domain": null,
                        "tracking_domain": null,
                        "global_merge_vars": {
                            "name": "merge1",
                            "content": "merge1 content"
                        },
                        "view_content_link": null,
                        "recipient_metadata": {
                            "rcpt": "recipient.email@example.com",
                            "values": {
                                "user_id": 123456
                            }
                        },
                        "return_path_domain": null,
                        "preserve_recipients": null,
                        "google_analytics_domains": "",
                        "google_analytics_campaign": "message.from_email@example.com"
                    },
                    "send_at": "example send_at",
                    "template_name": "example template_name",
                    "template_content": {
                        "name": "example name",
                        "content": "example content"
                    }
                },
                "response": {
                    [{}
                    ],
                    "_id": "abc123abc123abc123abc123abc123",
                    "email": "recipient.email@example.com",
                    "status": "sent",
                    "reject_reason": "hard-bounce"
                }
            }
        },
        "chanId": "",
        "channel": "",
        "interactionType": ""
    }
}

Setup 

• Follow the instructions for the setup of the Application Parameters Graph Template.
• Create a Mandrill account.
• Log in to https://mandrillapp.com/settings, create (if required) and retrieve the API key.
• Create the required tables using the SQL below.

INSERT INTO appParams(paramKey,paramValue,paramType,description) VALUES
('mandrillAPIKey', 'YOUR API KEY GOES HERE', 'string', 'This is the API Key for Mandrill');

• Create chanIPGeoLkup

CREATE TABLE interaction (
  kwInteractionId int(11) NOT NULL AUTO_INCREMENT,
  pId varchar(45) NOT NULL,
  channel varchar(30) DEFAULT NULL,
  interactionType varchar(20) DEFAULT NULL,
  ts datetime DEFAULT CURRENT_TIMESTAMP,
  direction varchar(45) DEFAULT NULL,
  PRIMARY KEY (kwInteractionId),
  KEY idx_pid (pId)
);

• Create chanIPGeoLkup

CREATE TABLE chanEmailMandrill (
  kwInteractionId int(11) NOT NULL,
  verb varchar(45) DEFAULT NULL,
  templateName varchar(256) DEFAULT NULL,
  mandrillId varchar(90) DEFAULT NULL,
  status varchar(45) DEFAULT NULL,
  reject_reason varchar(95) DEFAULT NULL,
  email varchar(256) DEFAULT NULL,
  requestRaw text,
  responseRaw text,
  PRIMARY KEY (kwInteractionId),
  UNIQUE KEY kwInteractionId_UNIQUE (kwInteractionId)
);

• Deploy the 'Mandrill - SendEmailTemplate' Template.
• Configure the Mandrilld REST Web Service connection with the following details:
  
• Endpoint: https://mandrillapp.com/api/1.0

Using

• Ensure there is credit in the Mandrill account.
• Place the mandrillSendEmailTemplate node in your graph.

• The expected outputs for this graph are true, 'metaSet' (indicates an error). The parent graph should also accommodate GoTo and Error branches.

• Set graph parameters "emailAddress", "recipientName", "templateName" and "mergeVars".
• The result of the Mandrill  webservice call is stored in  "{schema}.interaction.email.mandrill.response" and saved in the chanEmailMandrill table.

Notes: 

What is likely to go wrong

• Run out of Mandrill credit.

• Ensure you have credit in your account.

• The web service adaptor returns a "rejected", or "invalid" status. Check the reject_reason for rejects. 

• Inspect the interaction.email.mandrill.request body. It should look like this:

• Example Request

{
					"key": "example key",
					"async": false,
					"ip_pool": "Main Pool",
					"message": {
						"to": {
							"0": {
								"name": "Recipient Name",
								"type": "to",
								"email": "recipient.email@example.com"
							}
						},
						"html": "<p>Example HTML content</p>",
						"tags": "",
						"text": "Example text content",
						"merge": true,
						"images": {
							"name": "IMAGECID",
							"type": "image/png",
							"content": "ZXhhbXBsZSBmaWxl"
						},
						"headers": {
							"Reply-To": "message.reply@example.com"
						},
						"subject": "example subject",
						"metadata": {
							"website": "www.example.com"
						},
						"auto_html": null,
						"auto_text": null,
						"from_name": "Example Name",
						"important": false,
						"from_email": "message.from_email@example.com",
						"inline_css": null,
						"merge_vars": {
							"rcpt": "recipient.email@example.com",
							"vars": {
								"name": "merge2",
								"content": "merge2 content"
							}
						},
						"subaccount": "customer-123",
						"attachments": {
							"name": "myfile.txt",
							"type": "text/plain",
							"content": "ZXhhbXBsZSBmaWxl"
						},
						"bcc_address": "message.bcc_address@example.com",
						"track_opens": null,
						"track_clicks": null,
						"url_strip_qs": null,
						"merge_language": "mailchimp",
						"signing_domain": null,
						"tracking_domain": null,
						"global_merge_vars": {
							"name": "merge1",
							"content": "merge1 content"
						},
						"view_content_link": null,
						"recipient_metadata": {
							"rcpt": "recipient.email@example.com",
							"values": {
								"user_id": 123456
							}
						},
						"return_path_domain": null,
						"preserve_recipients": null,
						"google_analytics_domains": "",
						"google_analytics_campaign": "message.from_email@example.com"
					},
					"send_at": "example send_at",
					"template_name": "example template_name",
					"template_content": {
						"name": "example name",
						"content": "example content"
					}
				}

Typical Deliverables Plan

Use this plan to agree on the requirements of the Xponentuser and your client/ brand.

1. Client to configure the Mandrill account and provide Licence Key and User Key to KW user.
2. Client to configure the Mandrill email templates and provide KW user with template names, a list of merge_vars for each template.
   1. e.g. placeholders to be populated from request.
3. KW user to deploy Mandrill graph template and required environments.
4. Create SQL Assets.
   1. If using your own database:
      1. KW user to create SQL assets.
   2. If using the client's database:
      1. Provide the SQL creation code above for the brand to create.
      2. KW will need access to the database - see here for DB connections.
5. KW User to deploy the graph.