{"title":"Extend Email Capabilities","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-extending-email/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-extending-email, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-extending-email","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to extend the email capabilities in Business Central.","date":"2022-05-19","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Extend Email Capabilities","slug":"extend-email-capabilities","at":0,"chars":14489},{"level":2,"title":"Email architecture overview","slug":"email-architecture-overview","at":488,"chars":781},{"level":2,"title":"Email scenarios","slug":"email-scenarios","at":1269,"chars":1542},{"level":2,"title":"Email address book lookup","slug":"email-address-book-lookup","at":2811,"chars":4452},{"level":2,"title":"Email view policies","slug":"email-view-policies","at":7263,"chars":1714},{"level":2,"title":"Email accounts and connectors","slug":"email-accounts-and-connectors","at":8977,"chars":2078},{"level":2,"title":"Email importance example","slug":"email-importance-example","at":11055,"chars":3064},{"level":2,"title":"Related information","slug":"related-information","at":14119,"chars":370}],"text":"# Extend Email Capabilities\nBusiness Central offers built-in email capabilities that cover the needs of most businesses. You can share documents and information by email directly from Business Central.\nHowever, you might have a bright idea for something extra that would benefit your, or your customers', business. For example, you might want to use an email scenario that we don't provide. This article describes how you can extend the key components of our standard email capabilities.\n## Email architecture overview\nThe following diagram shows the key components of the out-of-the-box email capabilities.\n![Overview of the key parts of the email architecture]\nComponent|Description\nEmail scenarios|Define the business processes for which an email account will be used by default.\nEmail address book lookup|Sets how you find email addresses for specific entities.\nEmail view policies|Determine who has access to which email messages.\nEmail accounts and connectors|Specify the email providers and accounts that are connected to Business Central.\nEmail Outbox and Sent Email pages|Contain messages that haven't been sent, or have been sent, respectively.\nWe'll explore each of these components in more depth, and provide an example of how to extend their capabilities.\n## Email scenarios\nEmail scenarios are processes that involve sending a document. For example, a sales or purchase order or a notification that gives an external accountant access to your Business Central. You can use specific email accounts for specific scenarios. The following are a few examples:\n All users always send sales documents from account A.\n All users always send purchase documents from account B.\n All users always send warehouse or production documents from account C.\nThe following diagram shows the relationship between the objects for email scenarios.\nThe following code example shows how to extend the `Email Scenario` enum by adding a new scenario named BC LE Scenario. After you extend the enum, the new BC LE option is available in the Email Scenario field. You can assign the scenario to accounts on the Email Scenarios page, or by using the `EmailScenario.SetEmailAccount()` method.\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\nenumextension 50100 BCLEScenario extends \"Email Scenario\"​\n{​\n    value(999888; BCLEScenario)​\n    {​\n        Caption = 'BC LE Scenario';​\n    }​\n}​\n```\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\nprocedure AddEmailToScenario(Rec: Record \"Email Account\")\nvar\n    EmailScenario: Codeunit \"Email Scenario\";\n    NullGuid: Guid;\nbegin\n    if Rec.\"Account Id\" <> NullGuid then\n        EmailScenario.SetEmailAccount(Enum::\"Email Scenario\"::BCLEScenario, Rec)\n    else\n        Error('Trying to set an empty email account to BCLE email scenario');\nend;\n```\n## Email address book lookup\nThe email address book lookup is what you use to choose email accounts in Business Central from entities such as customers and vendors. The following diagram shows the relationship between the objects for the email address book lookup.\nThe following code example shows how to extend the `Email Address Entity` enum by adding a BCLE Entity option. The BCLE entity has an email address that we want to be able to access.\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\nenumextension 50110 \"BCLE - Address Book\" extends \"Email Address Entity\"​\n{​\n    value(50110; \"BCLE Entity\")​\n    {​\n        Caption = 'BCLE Entity';​\n    }​\n}\n\n```\nAfter you extend the `Email Address Entity` enum, subscribe to the OnGetSuggestedAddresses and OnLookupAddressFromEntity events. These events do the following:\n OnGetSuggestedAddresses gets email addresses from the records in the table that are related to an email that you are composing and displays them in the address book.\n OnLookupAddressFromEntity opens a modal dialog where you can choose the email addresses to add to the address book.\nThe following examples show how to implement the events.\n```al\nnamespace System.Email;\n\n[IntegrationEvent(false, false)]​\ninternal procedure OnGetSuggestedAddresses(TableId: Integer; SystemId: Guid; var Address: Record \"Email Address Lookup\")​\n\n[IntegrationEvent(false, false)]​\ninternal procedure OnLookupAddressFromEntity(Entity: Enum \"Email Address Entity\"; var Address: Record \"Email Address Lookup\"; var IsHandled: Boolean)\n```\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\nvar\n    NoRecordsFoundMsg: Label 'No %1 found with an email address.', Comment = '%1 Entity type';\n\n[EventSubscriber(ObjectType::Codeunit, Codeunit::\"Email Address Lookup\", 'OnLookupAddressFromEntity', '', false, false)]\nlocal procedure OnLookupAddressFromEntity(Entity: Enum \"Email Address Entity\"; var Address: Record \"Email Address Lookup\"; var IsHandled: Boolean)\nvar\n    BCLEEntity: Record \"BCLE Entity\";\n    BCLEEntityList: Page \"BCLE Entity List\";\nbegin\n    if not BCLEEntity.ReadPermission() or IsHandled or (Entity <> Entity::\"BCLE Entity\") then\n        exit;\n\n    BCLEEntity.SetFilter(\"Email\", '<>%1', '');\n    if not BCLEEntity.FindSet() then begin\n        Message(StrSubstNo(NoRecordsFoundMsg, BCLEEntity.TableCaption));\n        exit;\n    end;\n\n    BCLEEntityList.SetTableView(BCLEEntity);\n    BCLEEntityList.LookupMode := true;\n\n    if BCLEEntityList.RunModal() <> ACTION::LookupOK then begin\n        IsHandled := false;\n        exit;\n    end;\n\n    BCLEEntityList.SetSelectionFilter(BCLEEntity);\n    if BCLEEntity.FindSet() then\n        repeat\n            if StrLen(BCLEEntity.Email) > 0 then begin\n                Address.Name := BCLEEntity.\"Speaker Name\";\n                Address.\"E-Mail Address\" := BCLEEntity.Email;\n                Address.\"Source Table Number\" := Database::\"BCLE Entity\";\n                Address.\"Source System Id\" := BCLEEntity.SystemId;\n                Address.\"Entity type\" := Enum::\"Email Address Entity\"::\"BCLE Entity\";\n                Address.Insert();\n                IsHandled := true;\n            end;\n        until BCLEEntity.Next() = 0;\nend;\n\n[EventSubscriber(ObjectType::Codeunit, Codeunit::\"Email Address Lookup\", 'OnGetSuggestedAddresses', '', false, false)]\nlocal procedure SuggestedAddressesFromContacts(TableId: Integer; SystemId: Guid; var Address: Record \"Email Address Lookup\")\nvar\n    BCLEEntity: Record \"BCLE Entity\";\n    CompanyNo: Code[20];\nbegin\n    case TableId of\n        Database::\"BCLE Entity\":\n            begin\n                if not BCLEEntity.GetBySystemId(SystemId) then\n                    exit;\n                InsertAddressFromBCLEEntity(BCLEEntity, Address);\n            end;\n        else\n            exit;\n    end;\nend;\n\nlocal procedure InsertAddressFromBCLEEntity(var BCLEEntity: Record \"BCLE Entity\"; var Address: Record \"Email Address Lookup\")\nbegin\n    if ((BCLEEntity.Email <> '') and not Address.Get(BCLEEntity.Email, BCLEEntity.\"Speaker Name\", Enum::\"Email Address Entity\"::\"BCLE Entity\")) then begin\n        Address.Name := BCLEEntity.\"Speaker Name\";\n        Address.\"E-Mail Address\" := BCLEEntity.Email;\n        Address.\"Source Table Number\" := Database::\"BCLE Entity\";\n        Address.\"Source System Id\" := BCLEEntity.SystemId;\n        Address.\"Entity type\" := Enum::\"Email Address Entity\"::\"BCLE Entity\";\n        Address.Insert();\n    end;\nend;\n```\n## Email view policies\nEmail view policies give you control over the email messages that a user can access on the Email Outbox and Sent Emails pages. You can extend email view policies, for example by adding new policies, by customizing their types. The following diagram shows the relationship between the objects for email view policies.\nThe first step is to implement the `Email View Policy` interface.\n```al\nnamespace System.Email;\n\ninterface \"Email View Policy\"​\n{​\n    procedure GetSentEmails(var SentEmails: Record \"Sent Email\" temporary)\n    procedure GetOutboxEmails(var OutboxEmails: Record \"Email Outbox\" temporary)\n    procedure GetSentEmails(SourceTableId: Integer; var SentEmails: Record \"Sent Email\" temporary)\n    procedure GetOutboxEmails(SourceTableId: Integer; var OutboxEmails: Record \"Email Outbox\" temporary)\n    procedure GetSentEmails(SourceTableId: Integer; SourceSystemId: Guid; var SentEmails: Record \"Sent Email\" temporary)\n    procedure GetOutboxEmails(SourceTableId: Integer; SourceSystemId: Guid; var OutboxEmails: Record \"Email Outbox\" temporary)\n    procedure HasAccess(SentEmail: Record \"Sent Email\"): Boolean\n    procedure HasAccess(OutboxEmail: Record \"Email Outbox\"): Boolean\n}\n```\nNext, we'll extend the `Email View Policy` enum by adding a BE LE View Policy option.\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\nenumextension 50108 \"BC LE View Policy\" extends \"Email View Policy\"​\n{​\n    value(50108; \"BC LE View Policy\")​\n    {​\n        Caption = 'BC LE View Policy';​\n        Implementation = \"Email View Policy\" = BCLEViewPolicy;​\n    }​\n}\n```\nThe last step is to assign the email view policies to users. See /admin-how-setup-email#set-up-view-policies.\n## Email accounts and connectors\nA connector is the interface for creating and managing email accounts, and for sending emails from the accounts. The following table lists the connectors that are available by default.\nConnector|Description\nMicrosoft 365 Connector|Everyone sends email from a shared mailbox in Exchange Online.\nCurrent User Connector|Everyone sends email from the account they used to sign in to Business Central.\nSMTP Connector|Use SMTP protocol to send emails.\n> NOTE\n> The Microsoft 365 Connector and Current User Connector require that the user has a mailbox on the tenant.\nAll email accounts use a connector, and the accounts contain the information needed to send email messages. The following diagram shows the relationship between the objects for email accounts and connectors.\nThe first step is to implement the `Email Connector` interface.\n```al\nnamespace System.Email;\n\ninterface \"Email Connector\"​\n{​\n    procedure Send(EmailMessage: Codeunit \"Email Message\"; AccountId: Guid)\n    procedure GetAccounts(var Accounts: Record \"Email Account\")\n    procedure ShowAccountInformation(AccountId: Guid)\n    procedure RegisterAccount(var EmailAccount: Record \"Email Account\"): Boolean​\n    procedure DeleteAccount(AccountId: Guid): Boolean​\n    procedure GetLogoAsBase64(): Text\n    procedure GetDescription(): Text[250]\n}\n```\nNext, we'll extend the `Email Connector` enum by adding an SMTP option.\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\nenumextension 50200 \"My Email Connectors\" extends \"Email Connector\"\n{​\n    value(2147483647; SMTP)​\n    {​\n        Caption = 'SMTP';​\n        Implementation = \"Email Connector\" = \"SMTP Connector Impl.\";​\n    }​\n}\n```\nThe last step is to create a page where we can view or create an email account. See devenv-pages-overview.\n> TIP\n> If you want more details, there are several examples available on the ALAppExtensions repository<https://github.com/microsoft/ALAppExtensions/tree/main/Apps/W1/Email%20-%20SMTP%20Connector/app>. For example, the SMTP Connector is a good implementation to explore.\n## Email importance example\nThe following example shows how to extend the email capabilities by adding an importance field to email messages. This pattern extends both the `Email Outbox` and `Sent Email` tables and their corresponding pages to expose the new field.\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\nenum 50109 \"Email Importance\"\n{\n    Extensible = true;\n\n    value(0; Normal)\n    {\n        Caption = 'Normal';\n    }\n\n    value(1; Important)\n    {\n        Caption = 'Important';\n    }\n\n    value(2; \"Super Important\")\n    {\n        Caption = 'Super Important';\n    }\n}\n```\nTable extensions to add a new Importance field.\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\ntableextension 50110 \"Importance On Sent\" extends \"Sent Email\"\n{\n    fields\n    {\n        field(50109; \"Importance\"; Enum \"Email Importance\")\n        {\n            DataClassification = SystemMetadata;\n        }\n    }\n}\n\ntableextension 50109 \"Importance On Outbox\" extends \"Email Outbox\"\n{\n    fields\n    {\n        field(50109; \"Importance\"; Enum \"Email Importance\")\n        {\n            DataClassification = SystemMetadata;\n        }\n    }\n}\n```\nPage extensions on the Email Editor and Email Viewer that allow the Importance field to be viewed and changed.\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\npageextension 50111 \"Importance On Editor\" extends \"Email Editor\"\n{\n    layout\n    {\n        addafter(CcField)\n        {\n            field(Importance; Rec.Importance)\n            {\n                ApplicationArea = All;\n                Caption = 'Importance';\n                ToolTip = 'Specifies the importance of the email';\n            }\n        }\n    }\n}\n```\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\npageextension 50103 \"Importance On Email Viewer\" extends \"Email Viewer\"\n{\n    layout\n    {\n        addafter(CcField)\n        {\n            field(Importance; Rec.Importance)\n            {\n                ApplicationArea = All;\n                Caption = 'Importance';\n                ToolTip = 'Specifies the importance of the email';\n            }\n        }\n    }\n}\n```\nPage extensions for the Email Outbox and Sent Emails to display the Importance field.\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\npageextension 50109 \"Importance On Outbox\" extends \"Email Outbox\"\n{\n    layout\n    {\n        addafter(Desc)\n        {\n            field(Importance; Rec.Importance)\n            {\n                ApplicationArea = All;\n                Caption = 'Importance';\n                ToolTip = 'Specifies the importance of the email';\n            }\n        }\n    }\n}\n```\n```al\nnamespace MyCompany.EmailExtension;\n\nusing System.Email;\n\npageextension 50110 \"Importance On Sent\" extends \"Sent Emails\"\n{\n    layout\n    {\n        addafter(Desc)\n        {\n            field(Importance; Rec.Importance)\n            {\n                ApplicationArea = All;\n                Caption = 'Importance';\n                ToolTip = 'Specifies the importance of the email';\n            }\n        }\n    }\n}\n```\n## Related information\ndevenv-system-application-overview\nSet Up Email</admin-how-setup-email>\nModule System Application<https://learn.microsoft.com/dynamics365/business-central/application/system-application/module/system-application>\nModule Base Application<https://learn.microsoft.com/dynamics365/business-central/application/base-application/module/base-application>"}