Description

Use this function to send bulk email from your Alpha application via SparkPost. Rather than actually sending the email from your server, it generates a JSON string from parameters you define, and POSTs this package to SparkPost's API. The package is validated and then email is immediately queued for delivery. The benefit of using the API is that email is sent significantly faster with less burden on your own server.


SparkPost is at http://sparkpost.com/.

For Users of email_send_mandrill()

This function was made to be very similar to the existing Alpha function named email_send_mandrill(). It uses all of the same parameters and methods. But please read through this document for minor differences.

Installation 

  • Download and copy the wt_email_send_sparkpost.aex file to your projects folder and publish it to your server. Sometimes you have to restart your Alpha Web Server for it to take if you are updating the aex file.
  • Add wt_email_send_sparkpost.aex to your Project Properties under AEX Files.
  • Publish at least one file to push these changes to your server.

Requirements

  • You need a SparkPost account and an API Key. This function supports the SparkPost account level, not SparkPost Elite.
  • If you omit the <SPARKPOST API KEY> in the function parameters, then you can place it in the Project Properties / Application Global Variables like this: 
    sparkpost_key = "abc123"
  • If you omit the <SPARKPOST API KEY> in both the function parameter and the Project Properties, the function will fail immediately.
  • SparkPost does not really support CC or BCC. It sends an email to each recipient individually. If you provide email addresses for the ms.send_to_cc and ms.send_to_bcc it will just combine them as all TO addresses. If there are duplicate email addresses (across TO, CC and BCC) it will send multiple emails to that individual.

Parameters

Parameter

Required

Notes

ms.send_to

Yes

One or more valid email address separated by comma with optional friendly name for each email delimited with a colon.
Examples: 1) steve@sqst.com, 2) steve@sqst.com:Steve Wood

ms.send_to_cc

No

ms.send_to_bcc

No

ms.from_email

Yes

Must match your SparkPost domain for the API Key or it will reject your request.

ms.from_email_name

No

ms.subject

Yes

Requires at least one character in this field.

ms.message_html

No

Technically not required but no message will be sent if blank.

ms.message_text

No

Rarely used, older email clients only.

Function Call

dim pResult as p = wt_email_send_sparkpost("<SPARKPOST API KEY>",ms)

Returns

Variable

Type

Contents

pResult.body

C

Json string returned by SparkPost. Will contain details or an error message.

pResult.json

C

Json submitted to SparkPost by the function.

pResult.error

L

Returns .t. if SparkPost returned and error.

pResult.version

C

The version number of this function.

pResult.error_text

C

Error messages from the function (not from SparkPost)


Attachments

Attachment Method 1 - Simple list

'==Note - 'file exists' error checking is built in to the function for this attachments list

dim ms.attachments as c = ""

ms.attachments = "c:\a5\scratch.pdf,c:\a5\aero1.csv"

Attachment Method 2 - Array of attachments

'==Note - you will need to add your own error checking to ensure file exists for the attachmentsArray 

dim ms.attachmentsArray[1] as p

ms.attachmentsArray[1].type          = resolve_mime_type("pdf")

ms.attachmentsArray[1].name           = "scratch.pdf"

ms.attachmentsArray[1].content = base64encode(file.to_blob("c:\a5\scratch.pdf"))

Global Merge Feature

Global merge can be used in the Subject and Message Body.

Use this format for including email-specific merge variables: ^|variableName|^

Example:

ms.subject = "SparkPost Test by ^|FNameGlobal|^"

...

dim ms.global_merge_vars[1] as p

ms.global_merge_vars[1].name                 = "FnameGlobal"

ms.global_merge_vars[1].content         = "Global Steve Wood"

Email-Specific Merge Feature

Email-specific merge can be used in the Subject and Message Body.

Use this format for including email-specific merge variables: *|variableName|*

'==INDIVIDUAL MERGE VARIABLES. EXAMPLES

ms.message_html                = "<b>Test HTML Message</b> for *|Fname|* *|Lname|*" ' Example email-specific merge fields

...

dim ms.merge_vars[2] as p

dim ms.merge_vars[1].vars[1] as p ' one email, one item

ms.merge_vars[1].recp                         = "steve1@sqst.com"

ms.merge_vars[1].vars[1].name         = "Fname"

ms.merge_vars[1].vars[1].content         = "Steve (email-specific merge)"

dim ms.merge_vars[2].vars[2] as p ' one email, two items

ms.merge_vars[2].recp                         = "steve2@sqst.com"

ms.merge_vars[2].vars[1].name         = "Fname"

ms.merge_vars[2].vars[1].content         = "Ralph (email-specific merge)"

ms.merge_vars[2].vars[2].name         = "Lname"

ms.merge_vars[2].vars[2].content         = "Wood (email-specific merge)"

DataSource Method

Instead of the Email-Specific Merge method above, include a section similar to below and include merge fields in the Subject, Message HTML and/or Message Text areas using format {{ variableName }}. If you set the ms.dataSource variable, it will take precedence over the ms.email_to and ms.merge_vars. The values "Fname", "Lname" in the example below are the variableNames.


Notes: 

  • Also set ms.email_to to any non-null value such as ms.email_to = "none".
  • The email parameter MUST be the first one in the list, as shown below.


'==DATASOURCE. EXAMPLE

dim ms.dataSource as c = <<%txt%

[

{ email:"steve@sqst.com",  Fname: "Steve",  Lname: "Smith"  },

{ email:"steve1@sqst.com", Fname: "Steve1", Lname: "Smith1" }

]

%txt%

Debugging

'==SUGGESTED DEBUGGING. UNCOMMENT TO TEST IN A5W PAGE OR SEND TO A FILE TO REVIEW

?"ERROR   : " + pResult.error_text + "<hr>" '==ERRORS FOM THE ALPHA FUNCTION, NOT FROM SPARKPOST

?"RETURNED: " + pResult.body + "<hr>"        '==RETURNED FROM SPARKPOST IN JSON

?"POSTED  : " + pResult.json + "<hr>"        '==WHAT WE POSTED TO SPARKPOST

?"APIERROR: " + convert_type(pResult.error,"C") + "<hr>" '==True IF SPARKPOST RETURNED AN ERROR OF ANY KIND

?"VERSION : " + pResult.version + "<hr>"        '==VERSION OF THE ALPHA FUNCTION


'==SUGGESTED DEBUGGING IN A COMPONENT

dim pResult as p = wt_email_send_sparkpost("",ms)

if pResult.error = .t. then

    save_to_file(pResult.body + crlf(2) + pResult.json,"c:\a5\sparkpost_error.txt")

end if

(or use a javascript alert() to view messages)