Mandrill Send Email-Template

This graph allows Kitewheel 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 personalised, 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 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 Expand source

  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 Expand source

  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 accounte
• Place the mandrillSendEmailTemplate node in your graph
  
  • The expected outputs for this graph are true, 'metaSet' (indicates error). The parent graph should also accomodate 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 Expand source

    {
    					"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 the requirements from the Kitewheel User and your client/ brand