email_send_sendgrid Function

Syntax

Arguments

keyCharacter

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

See API Keys (SendGrid)|https://docs.sendgrid.com/ui/account-and-settings/api-keys for information on how to create a SendGrid API key.

messageCharacter Pointer

A JSON string or dot variable that defines the message properties:

from_emailCharacter

Required. The verified sender address for your SendGrid account.

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() or get_from_file() to encode image contents for the message.

Returns

resultPointer

Returns a dot variable that includes information about whether or not the message was delivered to the SendGrid server. The returned dot 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.

Description

Sends an email using the SendGrid service.

Discussion

The email_send_sendgrid() function can be used to send an email to one or more recipients using the SendGrid service.

Example

dim key as c = "SG.XXXXXXXXXXXXXXXXXXXXXXXXX" 'Replace with your SendGrid API key

dim ms as p
ms.send_to = "[email protected]"

ms.reply_to = "[email protected]" ' optional

ms.from_email = "[email protected]" ' must be the verified sender address
ms.from_name = "Sales" 'friendly name - optional

ms.subject = "Information You Requested"

ms.message_html = "Here is the <b>information</b> you requested."
ms.message_text = "Here is the information you requested."

pp = email_send_sendgrid(key,ms)

A more Complex Example

dim key as c = "SG.XXXXXXXXXXXXXXXXXXXXXXXXX" 'Replace with your SendGrid API key

dim ms as p
ms.send_to = "[email protected]:John Smith,[email protected]:Sally Greene"
ms.send_to_cc = "[email protected]"
ms.send_to_bcc = "[email protected]"

ms.from_email = "[email protected]"
ms.from_name = "Sales at Acme"
ms.reply_to = "[email protected]"

ms.subject = "Information You Requested"

ms.message_html = "Here is the <b>information</b> you requested."
ms.message_text = "Here is the information you requested."

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

pp = email_send_sendgrid(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">

See Also

• email_send_sparkpost