Parent | Child | Previous | Next

Xbasic

email_send_sparkpost Function

IN THIS PAGE

Using email_send_sparkpost
Example
A more Complex Example
Defining Attachments
Inlining Images
Including Additional SparkPost options

Syntax

p Result = email_send_sparkpost(key as c, message as A)

Arguments

keyCharacter

Your SparkPost API key. Leave blank (an empty string) to use the API key stored in Web Project Properties.

messageCharacter Pointer

Can be a JSON string that defines the message or object with message properties listed below. See examples for more info.

from_emailCharacter

Required. The sender's address.

from_nameCharacter

Friendly name to use in the from field.

reply_toCharacter

The email address to when the recipient replies to the message.

send_toCharacter

Required. The recipient's address. Multiple recipients can be specified as a comma-delimited list.

send_to_ccCharacter

Additional recipients to copy on the email message. Multiple recipients can be specified as a comma-delimited list.

send_to_bccCharacter

Additional recipients to blind carbon copy on the email message. Multiple recipients can be specified as a comma-delimited list.

subjectCharacter

Required. The email subject

message_htmlCharacter

Required. The email body defined as HTML.

message_textCharacter

Required. The email body defined as plain text.

attachmentsCharacter

A list of file attachments. Attachments can be defined as follows:

A comma delimited list of filenames located on the Application Server.
A comma delimited list of URLs that reference remote files.
A comma delimited list of JSON strings referencing files stored on Amazon S3 using the following format:
```
{
    "connectionString":"your storage connection string",
    "objectName":"name of the S3 object"
}
```

attachmentsArrayPointer

An array of files to attach to the email. Used instead of attachments to define a list of files to attach to the email. Each entry in the array must define the following properties:

nameCharacter: Required. The file name.
typeCharacter: Required. The file mime type. Use Context.ResolveMimeType() to get the appropriate mime type for the file.
contentCharacter: Required. The contents of the file as a base64 encoded string. Use base64encode() or get_from_file() to encode file contents for the message.

inlineImagesCharacter

A comma delimited list of images inlined in the email message using the format "path_to_image|imageName". Use <img src="cid:imageName"> to include images in the email message body where imageName is the image name specified in inlineImages.

See below for an example.

inlineImagesArrayPointer

An object array containing images to include in the email message. Each object in the array must define the properties below. Use <img src="cid:imageName"> to include images in the email message body where imageName is the name defined in the inlineImagesArray. See examples below for more information.

nameCharacter: Required. The image name. Used with cid: prefix to embed the image in the message. See examples below for more info.
typeCharacter: Required. The image mime type. Use Context.ResolveMimeType() to get the appropriate mime type for the image.
contentCharacter: Required. The contents of the image as a base64 encoded string. Use base64encode() to encode image contents for the message.

optionsPointer

Additional SparkPost options. Some options may not be available for your SparkPost subscription. See SparkPost Transmission Options for more detailed information.

start_timeCharacter: Specifies time when message should be sent. Time must be specified using the format YYYY-MM-DDTHH:MM:SS+-HH:MM
open_trackingLogical: Enables or disables open tracking.
initial_openLogical: Enables or disables initial open tracking.
click_trackingLogical: Enables or disables click tracking.
transactionalLogical: Whether or not the email should be marked as transactional.
sandboxLogical: Whether or not to use the sandbox sending domain.
skip_suppressionLogical: Whether or not customer suppression rules should be ignored.
ip_poolCharacter: The ID of a dedicated IP pool to use when sending the message.
inline_cssLogical: Whether to inline CSS in the <style> tags in the <head> of the email message.
perform_substitutionsLogical: Enable or disable substitutions.

Returns

ResultPointer

Returns an object that has the properties below that includes information about whether or not the message was delivered to the SparkPost server. The returned variable does not include information as to whether or not the message was delivered to each recipient. The return value also includes the JSON message definition that was constructed from the message object.

errorLogical

.t. if an error occurs. Otherwise .f..

errorTextCharacter

Information about why the email failed to send if error is .t..

jsonCharacter

A JSON string containing the message that was generated.

resultPointer

An object with the following properties:

errorsCharacter: An array of error messages, if any are returned by the function call.

Description

Send an email using the SparkPost service.

Using email_send_sparkpost

This Xbasic helper function can be used to send email using the SparkPost service. You must first go to sparkpost.com to get an API key. You will also be required to verify ownership of your sending domain.

Once you have your API key and have verified your domain ownership, you can send email.

Currently the email_send_sparkpost() function does not expose the ability to use merge variables in the HTML message. If you need this functionality, you must compose the message JSON manually. Refer to the SparkPost documentation.

Example

dim ms as p
ms.send_to = "[email protected]"
ms.from_email = "[email protected]"
ms.subject = "Greetings!"
ms.message_text = "Hello there!"

dim key as c = "" ' leave blank to use key stored in Web Project Properties

dim result as p
result = email_send_sparkpost(key,ms)

A more Complex Example

dim ms as p
ms.send_to = "[email protected]:Optional friendly name for John Smith,[email protected]"
ms.reply_to = "[email protected]" 'optional - use same format as send_to
ms.send_to_cc = "[email protected]" ' optional - use same format as send_to
ms.send_to_bcc = "[email protected]" ' optional - use same format as send_to 
ms.from_email = "[email protected]"
ms.from_name = "Sales at Acme" 'friendly name - optional
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:\alphasports\invoice.pdf,c:\alphasports\vendorlist.pdf"
dim key as c = "your sparkpostkey"
pp = email_send_SparkPost(key,ms)

Defining Attachments

Attachments can be included as a comma-delimited list in the attachments property. For example, to include two files from the Application Server, you would write:

ms.attachments = "c:\alphasports\invoice.pdf,c:\alphasports\vendorlist.pdf"

If the files are located remotely, you can instead specify them as URLS:

ms.attachments = "https://www.example.com/resources/invoice.pdf,https://www.example.com/resources/vendorlist.pdf"

To specify files from Amazon S3, use the JSON format for attachments. For example:

ms.attachments =<<%str%
{ "connectionString":"::storage::StorageS3", "objectName":"invoice.pdf"},{ "connectionString":"::storage::StorageS3", "objectName":"vendorlist.pdf"}
%str%

Where connectionString is a named Storage connection and objectName is the name of the object in the Amazon S3 bucket to attach. If the object is within a subdirectory in the bucket, include the subdirectory in the objectName. For example:

ms.attachments =<<%str%
{ "connectionString":"::storage::StorageS3", "objectName":"products/fallCatalog.pdf"}
%str%

You can mix and match attachments from various locations:

ms.attachments =<<%str%
c:\alphasports\invoice.pdf,https://www.example.com/resources/invoice.pdf,{ "connectionString":"::storage::StorageS3", "objectName":"invoice.pdf"}
%str%

You can alternatively define attachments using an array syntax via the attachmentsArray property. For example:

dim ms.attachmentsArray[3] as p
ms.attachmentsArray[1].name="localInvoice.pdf"
ms.attachmentsArray[1].type= Context.ResolveMimeType("pdf")
ms.attachmentsArray[1].content=get_from_file("c:\alphasports\invoice.pdf",.t.) 'base64 encode file

ms.attachmentsArray[2].name="remoteInvoice.pdf"
ms.attachmentsArray[2].type= Context.ResolveMimeType("pdf")
ms.attachmentsArray[2].content=get_from_file("https://www.example.com/resources/invoice.pdf",.t.) 'base64 encode file

ms.attachmentsArray[3].name="s3Invoice.pdf"
ms.attachmentsArray[3].type= Context.ResolveMimeType("pdf")
ms.attachmentsArray[3].content=get_from_file("{ "connectionString":"::storage::StorageS3", "objectName":"invoice.pdf"}",.t.) 'base64 encode file

Note that using attachmentsArray requires you to base64 encode the file content yourself. This can be done using get_from_file(), which can be used to fetch and base64 encode a file from the file system of the Application Server, a remote URL, or from Amazon S3.

Inlining Images

The body of your HTML message can optionally include in-line images. To define in-line images you can either use a property that specifies a comma-delimited list of image filenames or an object array.

To specify as a comma-delimited list of filenames:

ms.inlineImages = "c:\movieImages\4296.jpg|myimage1.jpeg"

Notice that the comma delimited names syntax specifies the image name (the name by which you will refer to the image in the HTML body) with a | delimiter. In the above example, the image name is 'myimage1.jpeg'

To specify as an object array:

dim ms.inlineImagesArray[1] as p
ms.inlineImagesArray[1].name = "myimage1.jpeg"
ms.inlineImagesArray[1].type = Context.ResolveMimeType("jpg")
ms.inlineImagesArray[1].content = get_from_file("C:\Images\4296.JPG",.t.) 'base64 encode file

Note that the image name used to refer to the image in the email message is specified using the name property.

To embed images in the HTML message body, use this syntax:

<img src="cid:imageName">

Where imageName is the value specified in the name property for an images array or the value after the | if defining images as a comma-delimited list. For example:

Check out this photo:<br><img src="cid:myimage1.jpeg">

Including Additional SparkPost options

SparkPost allows you to specify options, such as open_tracking and click_tracking (see SparkPost API documentation).

In build 4612 and newer, you can pass in these options to the email_send_sparkpost() function as shown below:

dim ms as p

'xbasic commands to set required properties of mp not shown

ms.options.open_tracking = .f.
ms.options.click_tracking = .f.
dim key as c = "your_sparkpost_key"

dim pp as p
pp = email_send_sparkpost(key,ms)