Alpha Software Blog

Filter by Category
show all


Alpha Anywhere Connecting to the "Mail Chimp for Apps" service

Richard Rabins
  Sending Email Using the Mandrill Email Service - Alpha Anywhere has always offered Xbasic functions to send email. However, these functions require that you have access to a SMTP mail server. The existing functions in Xbasic include:
  • email_send()
  • email_send2()
  • email_send_noprofile()
  • email_send_noprofile()
With the emergence of email services, such as Mandrill (www.mandrillapp.com) an alternate, possibly easier, and certainly more powerful way of sending emails from your applications is now possible. A new function,  email_send_mandrill()  allows you to send email using the Mandrill service. This is How Mandrill describes their service

MANDRILL -THE FASTEST WAY TO DELIVER EMAIL

Wherever you and your customers are, Mandrill can deliver your email in milliseconds. We’ve got servers all over the world. Mandrill is a scalable and affordable email infrastructure service, with all the marketing-friendly analytics tools you’ve come to expect from MailChimp.

Benefits of using a 3rd party emailing service include the easier setup, better deliverability, and access to powerful value added features offered by the service, such as tracking whether people open your email message, etc. The full functionality of the Mandrill email service can be read by navigating to this address: https://mandrillapp.com/api/docs/index.JSON.html In order to use the Mandrill email server, you will have to visit their web site and apply for a key. The key allows you to send a certain number of free emails each month. Beyond that, there is a fee. NOTE: Alpha Software is not involved in any way at all in the fee and does not receive any payment at all if you use the Mandrill service. There are two different ways in which you can use the email_send_mandrill() function. 1. Simple Method: Define Message Using Xbasic Dot Variable In the simple method, you define an Xbasic dot variable that defines the properties of the message you want to send and then you call email_send_mandrill(), passing in your Mandrill key and the dot variable. This simple method does not expose all of the functionality of the Mandrill service, but it is very easy to set up and use, and it is great for simple email messages. For example: 'create a .dot variable to define the message dim ms as p ms.send_to = "john@acme.com:John Smith,sally@acme.com:Sally Jones" ms.send_to_cc = "" ms.send_to_bcc = "" ms.from_email = "sales@alpha.com" ms.subject = "Information You Requested" ms.message_html = "Here is the <b>information</b> you requested." ms.message_text = "Plain text version of the message" ms.attachments = "c:\files\mychart1.pdf,c:\files\mytext1.txt" Notes About the Properties in the Dot Variable
  • The .send_to and .send_to_cc addresses are a comma delimited list of addresses. The email address is followed (optionally) by a colon and then a friendly name.
  • The .send_to_bcc property allows you to specify a single bcc address. If you specify more than one address, you will get an error.
  • .send_to_cc and .send_to_bcc are optional. You can omit them entirely.
  • .attachments is optional. It contains a comma delimited list of filenames to attach to the email.
CC and BCC Addresses Even though the Dot variable allows you to specify separate comma delimited lists for the TO and CC addresses, in reality, Mandrill does not support CC addresses. Furthermore, Mandrill only supports a single BCC address. If you specify any CC addressesl, the TO list and the CC list of addresses is combined into a single list and the emails are sent to all addresses in the combined list. However, the Mandrill internal .preserve_recipients property is set to false, so that none of the recipients will see the names of any other recipients. If you provided a list of names in the TO list, and no names in the CC list, the recipients of the email would all be able to see the names of the other recipients. Once you have defined the .dot variable, you can send the message. For example dim pResult as p pResult = email_send_mandrill("mysecretkey",ms) The function returns a .dot variable with several properties:
  • .error - a logical value .t. or .f.
  • .result - an Xbasic array with one item for each address in the recipient list
  • .json - the JSON settings that were constructed from the .dot variable passed into the function. You can use this value as a starting point should you wish to use the second method (described below) for calling the email_send_mandrill() function
Here is what a typical item in the .result array looks like: result[1].email = "john@acme.com" result[1].status = "sent" result[1]._id = "some message id" --- used to make queries against the Mandrill API for message status Here is a complete example of sending an email in the simplest possible way (eliminating all optional properties in the Xbasic .dot variable). As you can see, it just a few lines of code. 'create a .dot variable to define the message dim ms as p ms.send_to = "john@acme.com:John Smith,sally@acme.com:Sally Jones" ms.from_email = "sales@alpha.com" ms.subject = "Information You Requested" ms.message_html = "Here is the <b>information</b> you requested." dim pResult as p pResult = email_send_mandrill("mysecretkey",ms) Alternative Method for Specifying Attachments - Specifying the Attachment Data We have previously indicated that attachments are specified by setting the .attachments property to a comma delimited list of filenames. An alternative method is to set the .attachmentsArray property as a property array with .name, .typeand .content properties. Where:
  • .name - the filename (no drive/path, just the name and extension) of the file.
  • .type - the mime type
  • .content - the base64 encoded data
For Example dim ms.attachmentsArray[1] as p ms.attachmentsArray[1].name = "chart.pdf" ms.attachmentsArray[1].type = resolve_mime_type("pdf") ms.attachmentsArray[1].content = base64encode(file.to_blob("c:\myfiles\chart.pdf")) Merge Variables - Mail Merge Variables into the Message Body and Subject An advanced feature of the Mandrill service is to allow you to specify placeholders in the message subject and body that will be replaced with variables that you supply at the time Mandrill sends out the email to each recipient. The format for the placeholders is: *|VariableName|* For example, here is how the message subject or body could have been specified using placeholders: ms.subject = "*|Fname|*, here is the Information You Requested" ms.message_html = "*|Fname|* *|Lname|* here is the information you requested." When you use placeholders in the subject or body, you must specify the placeholder values. Obviously, you need to specify placeholder values for each recipient. For example, assume that you had specified two recipients as follows: ms.send_to = "john@acme.com:John Smith,sally@acme.com:Sally Jones" You would then need to specify the FName and LName variables for john@acme.com and for sally@acme.com. Here is how you would do this: 'define the .merge_vars[] array with 2 items dim ms.merge_vars[2] as p 'define the actual variables for the first recipient. 'since there are two variables, we define a sub-array with two items dim ms.merge_vars[1].vars[2] as p 'here are the variables for the first recipient ms.merge_vars[1].vars[1].name = "FName" ms.merge_vars[1].vars[1].content = "John" ms.merge_vars[1].vars[2].name = "LName" ms.merge_vars[1].vars[2].content = "Smith" ms.merge_vars[1].rcpt = "john@acme.com 'here are the variables for the second recipient dim ms.merge_vars[2].vars[2] as p ms.merge_vars[2].vars[1].name = "FName" ms.merge_vars[2].vars[1].content = "Sally" ms.merge_vars[2].vars[2].name = "LName" ms.merge_vars[2].vars[2].content = "Jones" ms.merge_vars[2].rcpt = "sally@acme.com In addition to supplying merge variables for each recipient, you can also supply global merge variables - for all recipients. You do this by specifying the .global_merge_vars property array. If a merge variable is defined at the individual recipient level, it will override the corresponding global merge variable. For example: dim ms.global_merge_vars[1] as p ms.global_merge_vars[1].name = "Company" ms.global_merge_vars[1].content = "Alpha Software" Using a DataSource Property Instead of supplying the actual email addresses and merge variables directly in the dot variable you can pass in a 'dataSource' (an array of JSON objects), and then indicate that the .send_to property should be populated from the data source. For example, consider the following definition of the .dataSource property: ms.dataSource = <<%txt% [ {email: "sam@acme.com", firstName: "Sam", lastname: "Smith"}, {email: "joe@acme.com", firstName: "Joe", lastname: "Jones"} ] %txt% If the above .dataSource property has been defined, then you can define the .sent_to property as follows: ms.send_to = "{datasource:email}" This indicates that the .send_to property should be populated from the 'email' property in the dataSource. If you pass in a .dataSource property, then there is no need to pass in the .merge_vars property - these properties are automatically generated from the data in the .dataSource property. Here is what happens if you pass in a .dataSource property: The .message_html, .message_text and .subjectproperties are scanned to see if any merge-variables are used. If any merge variables are found in any of these properties, then the merge variables for each address are automatically extracted from the .dataSource property. Using the .dataSource property, it is extremely easy to create a mass mailing with custom merge variables for each recipient.   2. Advanced Method: Define Message Using a JSON String The JSON method exposes the full functionality of the Mandrill service. To see all of the options that are available, please see the Mandrill API documentation. If you want to use advanced features, like track opens, or schedule delivery, you will need to use this option. Here is an example of how you can use this method: DIM json as C = <<%str% { "message": { "to": [ { "email": "john@acme.com", "name": "John Smith" } ], "from_email": "Sales@alpha.com", "subject": "Information You Requested", "html": "Here is the <b>information</b> you requested", "text": "Plain Text Message", "preserve_recipients": false }, "asynch": false, "ip_pool": null, "send_at": null } %str% dim pResult as p pResult = email_send_mandrill("mysecretkey",json) Generating the JSON String From Xbasic Xbasic has powerful functions for generating JSON from an Xbasic dot variable. For example, the json_generate() function will generate JSON from a .dot variable.  A powerful way to programmatically construct the JSON string that you pass into the email_send_mandrill() function is to build up an Xbasic .dot variable with the various properties that you want to set, then call json_generate() to generate the JSON.  
Prev Post Image
Continuous Improvements and Innovation -- What you Get with Alpha Anywhere
Next Post Image
"You Have to Accommodate Mobile as well as Desktop/Web Development"

About Author

Richard Rabins
Richard Rabins

Co-founder of Alpha Software, Richard Rabins focuses on strategy, sales, and marketing. Richard also served as CEO of SoftQuad International from 1997 to 2001, when it owned Alpha. In addition to his 30 years with the company, Richard played a key role as co-founder, and served as president and chairman of the Massachusetts Software Council (now the Massachusetts Technology Leadership Council), the largest technology trade organization in Massachusetts. Prior to founding Alpha, Richard was a project leader and consultant with Information Resources, Inc. (IRI), and a management consultant with Management Decision Systems, Inc. Richard holds a master's degree in system dynamics from the Sloan School at MIT, and a bachelor's degree in electrical engineering and master's degree in control engineering from University of the Witwatersrand in Johannesburg, South Africa. He has served on the boards of Silent Systems, Legacy Technology and O3B Networks, and is co-founder of Tubifi www.tubifi.com.

The Alpha platform is the only unified mobile and web app development and deployment environment with distinct “no-code” and “low-code” components. Using the Alpha TransForm no-code product, business users and developers can take full advantage of all the capabilities of the smartphone to turn any form into a mobile app in minutes, and power users can add advanced app functionality with Alpha TransForm's built-in programming language. IT developers can use the Alpha Anywhere low-code environment to develop complex web or mobile business apps from scratch, integrate data with existing systems of record and workflows (including data collected via Alpha TransForm), and add additional security or authentication requirements to protect corporate data.

Comment