How to send an email from AL?

A recurring question I get is how to send emails from AL in Business Central. In this video, I do a simple walkthrough of how to send emails via AL. Check it out:

https://youtu.be/tVjHP8JB10E

In this video, Erik shows how straightforward it is to send an email from AL in Business Central using the modern email APIs. He addresses a common problem: developers searching online often find outdated solutions involving legacy SMTP code units, when in reality, sending an email now takes just a few lines of code.

The Problem with Searching for Old Solutions

Erik has noticed that many developers approach sending emails from AL in overly complicated ways. The root cause? When you Google “how to send an email from AL,” you get results spanning 20 years of AL code history. If you don’t specifically filter out SMTP-related answers, you end up with legacy approaches that are far more complex than what’s needed today.

The good news: sending emails in modern AL has become dramatically simpler. It’s essentially just a few lines of code.

Understanding Codeunits as Objects

Before diving into the email code, Erik takes a moment to explain an important concept about codeunits that isn’t always obvious. In modern AL, codeunits serve two different purposes:

  1. Classic code library: A codeunit like Codeunit 80 (Sales-Post) that you create a variable for, call its functions, and move on. The codeunit itself isn’t really “a thing” — it’s just a container for procedures.
  2. Object with state: A codeunit variable that acts as an object with methods, values, and data. You think of it as an instance that holds information.

The new email functionality uses codeunits in the second way — as objects with state. This is key to understanding how the email API works.

The Two Components: Email Message and Email

1. Creating the Message

The first component is the Email Message codeunit. Think of this as your message object. When you look at its definition (F12 in VS Code), you’ll see functions like:

  • Create — initialize the message with recipients, subject, and body
  • GetBody / SetBody / AppendToBody — manage the email body
  • GetSubject — retrieve the subject line
  • GetRecipients / SetRecipients — manage recipients
  • AddAttachment — attach files
  • IsBodyHTMLFormatted — check if the body is HTML

There are also multiple overloads of the Create function. You can specify whether the body is HTML formatted, pass recipients as a list, and include CC and BCC recipients.

2. Sending the Message

The second component is the Email codeunit. This one works more like a traditional code library — you call its Send function and pass in the message object. The Send function takes an Email Message codeunit as its parameter.

The Simplest Example: Two Lines of Code

At its simplest, sending an email is just two lines of code — create the message, then send it:

TheMessage.Create('erik@hougaard.com', 'Hello Friend', 'This is the body');
Email.Send(TheMessage);

That’s it. Behind the scenes, Business Central will grab the default email account — whether that’s configured as SMTP, Microsoft 365, or any other connector. You don’t need to care about the underlying transport mechanism. You create a message and you send it.

Adding Attachments

If you need to attach a file, you use the AddAttachment method on the message object. The attachment content needs to be provided as a Base64-encoded string, which you can obtain using the Base64 Convert codeunit:

TheMessage.AddAttachment('myfile.zip', 'application/zip', base64.ToBase64(InS));

Complete Example

Here’s the full working example from the video, showing how all the pieces fit together:

pageextension 50100 CustomerListExt extends "Customer List"
{
    trigger OnOpenPage();
    var
        TheMessage : Codeunit "Email Message";
        Email : Codeunit Email;
        base64 : Codeunit "Base64 Convert";
        InS: InStream;
    begin
        TheMessage.Create('erik@hougaard.com','Hello Friend', 'This is the body');
        TheMessage.AddAttachment('myfile.zip','application/zip',base64.ToBase64(InS));
        Email.Send(TheMessage);
    end;
}

Note: Erik placed this code in the OnOpenPage trigger purely for demonstration purposes — in a real application, you’d trigger email sending from a more appropriate location, such as an action or a business logic codeunit.

Email Scenarios and Account Selection

The Send function has additional overloads that give you more control:

  • Scenarios: You can specify a scenario (e.g., “this is an invoice,” “this is a statement”) and then configure in the email account setup which account should be used for each scenario. This lets you send invoices from one email address and statements from another.
  • Specific account: You can explicitly specify which email account and connector to use.
  • Open in Editor: Instead of sending immediately, you can call Email.OpenInEditor(TheMessage) to let the user review and modify the email before sending.

Conclusion

The modern email API in Business Central abstracts away all the complexity of the old SMTP-based approaches. You no longer need to worry about SMTP servers, authentication details, or low-level mail protocols in your AL code. The entire process boils down to: create a message object, optionally add attachments, and send it (or open it in the editor). Forget about the legacy code you find on the internet — this is the clean, supported, and much simpler way to handle emails in AL.

Picture of hougaard

hougaard