Developing with the new enhanced email feature

Yesterday, I had an email notification about a new blog post from my colleague Josh Anglesea. A great post on the new enhanced email feature coming with Business Central v17. Out of pure coincidence, I happened to be looking into the same functionality, but from a development perspective… So inspired by Josh here’s a blog post about developing with the new enhanced email feature.

Josh already did a great job explaining how to setup the new functionality, so I highly recommend you read his post before continuing as I won’t go into this.

The major change this new enhanced email functionality offers is the ability to configure multiple email accounts and have Business Central select the correct account based on the scenario. This is in contrast to the single account you can configure per Business Central company using the old SMTP Setup page.

This brings us to the first new concept: Email Scenario

When you create a new email account, you can choose which scenarios this account will be used in. The scenarios offered by the base application are defined in an enumextension object, which extends the systems app’s Email Scenario Enum:

enumextension 8891 "Base Email Scenario" extends "Email Scenario"
{
    value(1; "Invite External Accountant")
    {
        Caption = 'Invite External Accountant';
    }
    value(2; "Notification")
    {
        Caption = 'Notification';
    }
    value(3; "Job Planning Line Calendar")
    {
        Caption = 'Job Planning Line Calendar';
    }

    // Document usage

    // ------------------------------------------------------------------------------------------------

    value(100; "Sales Quote")
    {
        Caption = 'Sales Quote';
    }
    value(101; "Sales Order")
    {
        Caption = 'Sales Order';
    }
    value(102; "Sales Invoice")
    {
        Caption = 'Sales Invoice';
    }
    value(103; "Sales Credit Memo")
    {
        Caption = 'Sales Credit Memo';
    }
    value(105; "Purchase Quote")
    {
        Caption = 'Purchase Quote';
    }
    value(106; "Purchase Order")
    {
        Caption = 'Purchase Order';
    }
    value(115; "Reminder")
    {
        Caption = 'Reminder';
    }
    value(116; "Finance Charge")
    {
        Caption = 'Finance Charge';
    }
    value(129; "Service Quote")
    {
        Caption = 'Service Quote';
    }
    value(130; "Service Order")
    {
        Caption = 'Service Order';
    }
    value(131; "Service Invoice")
    {
        Caption = 'Service Invoice';
    }
    value(132; "Service Credit Memo")
    {
        Caption = 'Service Credit Memo';
    }
    value(184; "Posted Vendor Remittance")
    {
        Caption = 'Posted Vendor Remittance';
    }
    value(185; "Customer Statement")
    {
        Caption = 'Customer Statement';
    }
    value(186; "Vendor Remittance")
    {
        Caption = 'Vendor Remittance';
    }
}

Building your own functionality on top of this, you’ll probably want to add to the list of scenarios. Good news! This is as simple as extending the Email Scenario Enum in our own apps:

enumextension 50100 "Dan Test Email Scenario DDK" extends "Email Scenario"
{
    value(50100; "Dan Test 1 DDK")
    {
        Caption = 'Dan Test 1';
    }
    value(50101; "Dan Test 2 DDK")
    {
        Caption = 'Dan Test 2';
    }
}

Once you’ve created your enumextension, the new options are automatically included in the Email Scenario list:

Next up, we need to create an email message and send. This is done using the Email Message and Email Codeunits.

Note: The enhanced email app is part of the system app, so you won’t be able to see the source code from VS Code, or by extracting the base application app file. The system application apps are open source and available on GitHub to view and submit your own changes, the email app can be found here: https://github.com/microsoft/ALAppExtensions/tree/master/Modules/System/Email

The following example show how you can create an email message and send using the email scenario functionality:

    procedure SendEmail()
    var
        Email: Codeunit Email;
        EmailMessage: Codeunit "Email Message";
    begin
        EmailMessage.Create('dan@dankinsella.blog', 'My Subject', 'My message body text');
        Email.Send(EmailMessage, Enum::"Email Scenario"::"Dan Test 1 DDK");
    end;

As you can see, we can pass the email scenario into the send procedure. If an account is associated with this scenario it will be selected for use. If no account is assigned to this scenario the default account will be used.

Note the Email.Send() procedure is overloaded, meaning it can take different sets of parameters, so have a look at the object here for all the available options.

Some other cool stuff to check out:

You can open the new email editor using Email.OpenInEditor() to allow your users to edit the email before sending:

 /// <summary>
/// Opens an email message in "Email Editor" page.
/// </summary>
/// <param name="EmailMessage">The email message to use as payload.</param>
/// <param name="EmailScenario">The scenario to use in order to determine the email account to use on the page.</param>
procedure OpenInEditor(EmailMessage: Codeunit "Email Message"; EmailScenario: Enum "Email Scenario")
begin
    EmailImpl.OpenInEditor(EmailMessage, EmailScenario, false);
end;

We can also send the email in the background by putting it on the scheduler using Enqueue procedure:

 /// <summary>
/// Enqueues an email to be sent in the background.
/// </summary>
/// <param name="EmailMessage">The email message to use as payload.</param>
/// <param name="EmailScenario">The scenario to use in order to determine the email account to use for sending the email.</param>
procedure Enqueue(EmailMessage: Codeunit "Email Message"; EmailScenario: Enum "Email Scenario")
begin
    EmailImpl.Enqueue(EmailMessage, EmailScenario);
end;

Attachments can be added to the email message using an InStream, something like this:

    procedure SendEmailWithAttachment(AttachmentTempBlob: Codeunit "Temp Blob")
    var
        Email: Codeunit Email;
        EmailMessage: Codeunit "Email Message";
        AttachmentInStream: InStream;
    begin
        EmailMessage.Create('dan@dankinsella.blog', 'My Subject', 'My message body text');
        AttachmentTempBlob.CreateInStream(AttachmentInStream);
        EmailMessage.AddAttachment('My Attachment name', 'PDF', AttachmentInStream);
        Email.Send(EmailMessage, Enum::"Email Scenario"::"Dan Test 2 DDK");
    end;

The post Developing with the new enhanced email feature appeared first on Dan Kinsella.