Codeunit 8904 Email Message

System Application, System.Email

src/System Application/App/Email/src/Message/EmailMessage.Codeunit.al569 lines, Copyright (c) Microsoft Corporation. MIT

// ------------------------------------------------------------------------------------------------// Copyright (c) Microsoft Corporation. All rights reserved.// Licensed under the MIT License. See License.txt in the project root for license information.// ------------------------------------------------------------------------------------------------namespace System.Email;/// <summary>/// Codeunit to create and manage email messages./// </summary>codeunit 8904 "Email Message"{    Access = Public;    /// <summary>    /// Creates the email with recipients, subject, and body.    /// </summary>    /// <param name="ToRecipients">The recipient(s) of the email. A string containing the email addresses of the recipients separated by semicolon.</param>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">Raw text that will be used as body of the email.</param>    procedure Create(ToRecipients: Text; Subject: Text; Body: Text)    begin        EmailMessageImpl.Create(ToRecipients, Subject, Body, false);    end;    /// <summary>    /// Creates the email with recipients, subject, and body.    /// </summary>    /// <param name="ToRecipients">The recipient(s) of the email. A string containing the email addresses of the recipients separated by semicolon.</param>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">The body of the email.</param>    /// <param name="HtmlFormatted">Whether the body is HTML formatted.</param>    procedure Create(ToRecipients: Text; Subject: Text; Body: Text; HtmlFormatted: Boolean)    begin        EmailMessageImpl.Create(ToRecipients, Subject, Body, HtmlFormatted);    end;    /// <summary>    /// Creates the email with recipients, subject, and body.    /// </summary>    /// <param name="ToRecipients">The recipient(s) of the email. A string containing the email addresses of the recipients separated by semicolon.</param>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">The body of the email.</param>    /// <param name="HtmlFormatted">Whether the body is HTML formatted.</param>    /// <param name="Sanitize">If the body is of HTML formatting, most of it will be sanitized. Keeping only tags and no styling.</param>    /// <remarks>Sanitize is only applicable if the body is HTML formatted. It also helps prevent potential email messages from hiding images and text from the user.</remarks>    procedure Create(ToRecipients: Text; Subject: Text; Body: Text; HtmlFormatted: Boolean; Sanitize: Boolean)    begin        EmailMessageImpl.Create(ToRecipients, Subject, Body, HtmlFormatted, Sanitize);    end;    /// <summary>    /// Creates the email with recipients, subject, and body.    /// </summary>    /// <param name="ToRecipients">The recipient(s) of the email. A list of email addresses the email will be send directly to.</param>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">The body of the email</param>    /// <param name="HtmlFormatted">Whether the body is HTML formatted</param>    procedure Create(ToRecipients: List of [Text]; Subject: Text; Body: Text; HtmlFormatted: Boolean)    var        CCRecipients: List of [Text];        BCCRecipients: List of [Text];    begin        EmailMessageImpl.Create(ToRecipients, Subject, Body, HtmlFormatted, CCRecipients, BCCRecipients, false);    end;    /// <summary>    /// Creates the email with recipients, subject, and body.    /// </summary>    /// <param name="ToRecipients">The recipient(s) of the email. A list of email addresses the email will be send directly to.</param>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">The body of the email.</param>    /// <param name="HtmlFormatted">Whether the body is HTML formatted.</param>    /// <param name="CCRecipients">The CC recipient(s) of the email. A list of email addresses that will be listed as CC.</param>    /// <param name="BCCRecipients">TThe BCC recipient(s) of the email. A list of email addresses that will be listed as BCC.</param>    procedure Create(ToRecipients: List of [Text]; Subject: Text; Body: Text; HtmlFormatted: Boolean; CCRecipients: List of [Text]; BCCRecipients: List of [Text])    begin        EmailMessageImpl.Create(ToRecipients, Subject, Body, HtmlFormatted, CCRecipients, BCCRecipients, false);    end;    /// <summary>    /// Creates the email reply with recipients, subject, and body.    /// </summary>    /// <param name="ToRecipients">The recipient(s) of the email. A string containing the email addresses of the recipients separated by semicolon.</param>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">The body of the email.</param>    /// <param name="HtmlFormatted">Whether the body is HTML formatted.</param>    /// <param name="ExternalId">The external message id to reply to.</param>    procedure CreateReply(ToRecipients: Text; Subject: Text; Body: Text; HtmlFormatted: Boolean; ExternalId: Text)    begin        EmailMessageImpl.CreateReply(ToRecipients, Subject, Body, HtmlFormatted, ExternalId);    end;    /// <summary>    /// Creates the email reply with recipients, subject, and body.    /// </summary>    /// <param name="ToRecipients">The recipient(s) of the email. A list of email addresses the email will be send directly to.</param>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">The body of the email.</param>    /// <param name="HtmlFormatted">Whether the body is HTML formatted.</param>    /// <param name="ExternalId">The external message id to reply to.</param>    procedure CreateReply(ToRecipients: List of [Text]; Subject: Text; Body: Text; HtmlFormatted: Boolean; ExternalId: Text)    var        CCRecipients: List of [Text];        BCCRecipients: List of [Text];    begin        EmailMessageImpl.CreateReply(ToRecipients, Subject, Body, HtmlFormatted, ExternalId, CCRecipients, BCCRecipients);    end;    /// <summary>    /// Creates the email reply with recipients, subject, and body.    /// </summary>    /// <param name="ToRecipients">The recipient(s) of the email. A list of email addresses the email will be send directly to.</param>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">The body of the email.</param>    /// <param name="HtmlFormatted">Whether the body is HTML formatted.</param>    /// <param name="ExternalId">The external message id to reply to.</param>    /// <param name="CCRecipients">The CC recipient(s) of the email. A list of email addresses that will be listed as CC.</param>    /// <param name="BCCRecipients">TThe BCC recipient(s) of the email. A list of email addresses that will be listed as BCC.</param>    procedure CreateReply(ToRecipients: List of [Text]; Subject: Text; Body: Text; HtmlFormatted: Boolean; ExternalId: Text; CCRecipients: List of [Text]; BCCRecipients: List of [Text])    begin        EmailMessageImpl.CreateReply(ToRecipients, Subject, Body, HtmlFormatted, ExternalId, CCRecipients, BCCRecipients);    end;    /// <summary>    /// Creates the email replying to all existing recipents on the mail thread, subject, and body.    /// </summary>    /// <param name="Subject">The subject of the email.</param>    /// <param name="Body">The body of the email.</param>    /// <param name="HtmlFormatted">Whether the body is HTML formatted.</param>    /// <param name="ExternalId">The external message id to reply to.</param>    procedure CreateReplyAll(Subject: Text; Body: Text; HtmlFormatted: Boolean; ExternalId: Text)    begin        EmailMessageImpl.CreateReplyAll(Subject, Body, HtmlFormatted, ExternalId);    end;    /// <summary>    /// Gets the email message with the given ID.    /// </summary>    /// <param name="MessageId">The ID of the email message to get.</param>    /// <returns>True if the email was found; otherwise - false.</returns>    procedure Get(MessageId: Guid): Boolean    begin        exit(EmailMessageImpl.Get(MessageId));    end;    /// <summary>    /// Deletes messages that does not have a reference from either the email outbox nor sent email.    /// This functionality is only needed if email messages have been created without any email outbox or sent email referencing it, otherwise they will be cleaned up automatically.    /// </summary>    /// <param name="StartMessageId">The email message id to start from. Using empty guid will start from the beginning.</param>    /// <param name="MessagesToIterate">Number of email messages to loop over.</param>    /// <returns>The next email message id to be checked. Returns empty guid if there are no more messages.</returns>    procedure DeleteOrphanedMessages(StartMessageId: Guid; MessagesToIterate: Integer) NextMessageId: Guid    begin        exit(EmailMessageImpl.DeleteOrphanedMessages(StartMessageId, MessagesToIterate));    end;    /// <summary>    /// Deletes email recipients that do not have a reference from email message.    /// This functionality is only needed if email recipients have been created without any email message referencing it, otherwise they will be cleaned up automatically.    /// </summary>    /// <param name="StartMessageId">The email message id to start from. Using empty guid will start from the beginning.</param>    /// <param name="MessagesToIterate">Number of email messages to loop over.</param>    /// <returns>The next email message id to be checked. Returns empty guid if there are no more messages.</returns>    /// <remarks>Only the recipients that are not referenced by any email message will be deleted.</remarks>    procedure DeleteEmailRecipientsIfOrphaned(StartMessageId: Guid; MessagesToIterate: Integer) NextMessageId: Guid    begin        exit(EmailMessageImpl.DeleteEmailRecipientsIfOrphaned(StartMessageId, MessagesToIterate));    end;    /// <summary>    /// Gets the body of the email message.    /// </summary>    /// <returns>The body of the email.</returns>    procedure GetBody(): Text    begin        exit(EmailMessageImpl.GetBody());    end;    /// <summary>    /// Sets the body of the email message.    /// </summary>    /// <param name="Body">The body to set to the email message.</param>    procedure SetBody(Body: Text)    begin        EmailMessageImpl.SetBody(Body);    end;    /// <summary>    /// Appends to the body of the email message.    /// <param name="Value">The value to append to the body of the email message.</param>    /// </summary>    procedure AppendToBody(Value: Text)    begin        EmailMessageImpl.AppendToBody(Value);    end;    /// <summary>    /// Adds a header to the currently loaded message. If a header with the same name is already    /// present, the new value is appended after a line feed character so the full sequence is    /// preserved -- useful for headers that legitimately repeat (e.g. <c>Received</c>).    /// </summary>    /// <param name="HeaderName">Header name (case-insensitive).</param>    /// <param name="HeaderValue">Header value to append.</param>    /// <remarks>Mutations are buffered in memory. Call <see cref="FlushHeaders"/> to persist them    /// before the codeunit instance goes out of scope or before navigating to another message via    /// <c>Get</c>; unflushed changes are discarded otherwise.</remarks>    procedure AddHeader(HeaderName: Text; HeaderValue: Text)    begin        EmailMessageImpl.AddHeader(HeaderName, HeaderValue);    end;    /// <summary>    /// Sets a header on the currently loaded message, replacing any existing value for the same    /// name. Use <see cref="AddHeader"/> when repeated headers should accumulate.    /// </summary>    /// <param name="HeaderName">Header name (case-insensitive).</param>    /// <param name="HeaderValue">Header value to store.</param>    /// <remarks>Mutations are buffered in memory. Call <see cref="FlushHeaders"/> to persist them    /// before the codeunit instance goes out of scope or before navigating to another message via    /// <c>Get</c>; unflushed changes are discarded otherwise.</remarks>    procedure SetHeader(HeaderName: Text; HeaderValue: Text)    begin        EmailMessageImpl.SetHeader(HeaderName, HeaderValue);    end;    /// <summary>    /// Reads a single header value from the currently loaded message. Lookups are case-insensitive    /// on the header name. Repeated headers are returned as one string with values joined by a    /// line feed character in the order they were added.    /// </summary>    /// <param name="HeaderName">Header name to look up (case-insensitive, whitespace-trimmed).</param>    /// <param name="Value">Returned value when the header is present; empty otherwise.</param>    /// <returns><c>true</c> when a value was found.</returns>    /// <remarks>Reads include any unflushed mutations issued via <see cref="AddHeader"/> or    /// <see cref="SetHeader"/> on this codeunit instance.</remarks>    procedure GetHeader(HeaderName: Text; var Value: Text): Boolean    begin        exit(EmailMessageImpl.GetHeader(HeaderName, Value));    end;    /// <summary>    /// Persists any pending header mutations to the database in a single write. Safe to call when    /// nothing is pending. Call this after any sequence of <see cref="AddHeader"/> /    /// <see cref="SetHeader"/> calls so the changes survive the codeunit instance going out of    /// scope or a subsequent navigation to another message.    /// </summary>    procedure FlushHeaders()    begin        EmailMessageImpl.FlushHeaders();    end;    procedure GetExternalId(): Text[2048]    begin        exit(EmailMessageImpl.GetExternalId());    end;    /// <summary>    /// Gets the subject of the email message.    /// </summary>    /// <returns>The subject of the email.</returns>    procedure GetSubject(): Text[2048]    begin        exit(EmailMessageImpl.GetSubject());    end;    /// <summary>    /// Sets the subject of the email message.    /// </summary>    /// <param name="Subject">The subject to set to the email message.</param>    procedure SetSubject(Subject: Text)    begin        EmailMessageImpl.SetSubject(Subject);    end;    /// <summary>    /// Checks if the email body is formatted in HTML.    /// </summary>    /// <returns>True if the email body is formatted in HTML; otherwise - false.</returns>    procedure IsBodyHTMLFormatted(): Boolean    begin        exit(EmailMessageImpl.IsBodyHTMLFormatted());    end;    /// <summary>    /// Sets whether the email body is formatted in HTML.    /// <param name="Value">True if the email body is formatted in HTML; otherwise - false.</param>    /// </summary>    procedure SetBodyHTMLFormatted(Value: Boolean)    begin        EmailMessageImpl.SetBodyHTMLFormatted(Value);    end;    /// <summary>    /// Gets the ID of the email message.    /// </summary>    /// <returns>The ID of the email.</returns>    procedure GetId(): Guid    begin        exit(EmailMessageImpl.GetId());    end;    /// <summary>    /// Gets the recipents of a certain type of the email message.    /// </summary>    /// <param name="RecipientType">Specifies the type of the recipients.</param>    /// <param name="Recipients">Out parameter filled with the recipients' email addresses.</param>    procedure GetRecipients(RecipientType: Enum "Email Recipient Type"; var Recipients: List of [Text])    begin        Recipients := EmailMessageImpl.GetRecipients(RecipientType);    end;    /// <summary>    /// Sets the recipents of a certain type of the email message.    /// </summary>    /// <param name="RecipientType">Specifies the type of the recipients.</param>    /// <param name="Recipients">Specifies the list of the recipients' email addresses as a semicolon (;) separated list.</param>    procedure SetRecipients(RecipientType: Enum "Email Recipient Type"; Recipients: Text)    begin        EmailMessageImpl.SetRecipients(RecipientType, Recipients);    end;    /// <summary>    /// Sets the recipents of a certain type of the email message.    /// </summary>    /// <param name="RecipientType">Specifies the type of the recipients.</param>    /// <param name="Recipients">Specifies the list of the recipients' email addresses.</param>    procedure SetRecipients(RecipientType: Enum "Email Recipient Type"; Recipients: List of [Text])    begin        EmailMessageImpl.SetRecipients(RecipientType, Recipients);    end;    /// <summary>    /// Adds a recipient of a certain type to the email message.    /// </summary>    /// <param name="RecipientType">Specifies the type of the recipient.</param>    /// <param name="Recipient">Specifies the recipient's email address.</param>    procedure AddRecipient(RecipientType: Enum "Email Recipient Type"; Recipient: Text)    begin        EmailMessageImpl.AddRecipient(RecipientType, Recipient);    end;    /// <summary>    /// Adds a file attachment to the email message.    /// </summary>    /// <param name="AttachmentName">The name of the file attachment.</param>    /// <param name="ContentType">The Content Type of the file attachment.</param>    /// <param name="AttachmentBase64">The Base64 text representation of the attachment.</param>    /// <returns>True if the attachment was added; otherwise - false.</returns>    procedure AddAttachment(AttachmentName: Text[250]; ContentType: Text[250]; AttachmentBase64: Text)    begin        EmailMessageImpl.AddAttachment(AttachmentName, ContentType, AttachmentBase64);    end;    /// <summary>    /// Adds a file attachment to the email message.    /// </summary>    /// <param name="AttachmentName">The name of the file attachment.</param>    /// <param name="ContentType">The Content Type of the file attachment.</param>    /// <param name="AttachmentInStream">The instream of the attachment.</param>    /// <returns>True if the attachment was added; otherwise - false.</returns>    procedure AddAttachment(AttachmentName: Text[250]; ContentType: Text[250]; AttachmentInStream: InStream)    begin        EmailMessageImpl.AddAttachment(AttachmentName, ContentType, AttachmentInStream);    end;    /// <summary>    /// Adds a file attachment to the email message.    /// </summary>    /// <param name="AttachmentName">The name of the file attachment.</param>    /// <param name="ContentType">The Content Type of the file attachment.</param>    /// <param name="InLine">Specifies whether the attachment is inline.</param>    /// <param name="ContentId">The Content ID of the file attachment.</param>    /// <param name="AttachmentInStream">The instream of the attachment.</param>    /// <returns>True if the attachment was added; otherwise - false.</returns>    procedure AddAttachment(AttachmentName: Text[250]; ContentType: Text[250]; InLine: Boolean; ContentId: Text[40]; AttachmentInStream: InStream)    begin        EmailMessageImpl.AddAttachment(AttachmentName, ContentType, AttachmentInStream, InLine, ContentId);    end;    /// <summary>    /// Adds a file attachment to the email message.    /// </summary>    /// <param name="AttachmentName">The name of the file attachment.</param>    /// <param name="ContentType">The Content Type of the file attachment.</param>    /// <param name="InLine">Specifies whether the attachment is inline.</param>    /// <param name="ContentId">The Content ID of the file attachment.</param>    /// <param name="AttachmentInStream">The instream of the attachment.</param>    /// <param name="MessageAlreadyRetrieved">Specifies that the email message has already been retrieved into the email inbox.</param>    procedure AddAttachment(AttachmentName: Text[250]; ContentType: Text[250]; InLine: Boolean; ContentId: Text[40]; AttachmentInStream: InStream; MessageAlreadyRetrieved: Boolean)    begin        EmailMessageImpl.AddAttachment(AttachmentName, ContentType, AttachmentInStream, InLine, ContentId, MessageAlreadyRetrieved);    end;    /// <summary>    /// Adds attachments from scenario to the email message.    /// </summary>    /// <param name="EmailAttachments">The reference to the email attachments </param>    procedure AddAttachmentFromScenario(var EmailAttachments: Record "Email Attachments")    begin        EmailMessageImpl.AddAttachmentsFromScenario(EmailAttachments);    end;    /// <summary>    /// Deletes the contents of the currently selected attachment.    /// </summary>    /// <returns>Returns true if contents was successfully deleted, otherwise false.</returns>    procedure Attachments_DeleteContent(): Boolean    begin        exit(EmailMessageImpl.Attachments_DeleteContent());    end;    /// <summary>    /// Deletes the contents of the currently selected attachment.    /// </summary>    /// <param name="BypassSentCheck">If true, the attachment content will be deleted even if the email message has been sent.</param>    /// <returns>Returns true if contents was successfully deleted, otherwise false.</returns>    procedure Attachments_DeleteContent(BypassSentCheck: Boolean): Boolean    begin        exit(EmailMessageImpl.Attachments_DeleteContent(BypassSentCheck));    end;    /// <summary>    /// Deletes the currently selected attachment.    /// </summary>    /// <returns>Returns true if attachment was successfully deleted, otherwise false.</returns>    procedure Attachments_Delete(): Boolean    begin        exit(EmailMessageImpl.Attachments_Delete());    end;    /// <summary>    /// Deletes the currently selected attachment.    /// </summary>    /// <param name="BypassSentCheck">If true, the attachment will be deleted even if the email message has been sent.</param>    /// <returns>Returns true if attachment was successfully deleted, otherwise false.</returns>    procedure Attachments_Delete(BypassSentCheck: Boolean): Boolean    begin        exit(EmailMessageImpl.Attachments_Delete(BypassSentCheck));    end;    /// <summary>    /// Finds the first attachment of the email message.    /// </summary>    /// <returns>True if there is any attachment; otherwise - false.</returns>    procedure Attachments_First(): Boolean    begin        exit(EmailMessageImpl.Attachments_First());    end;    /// <summary>    /// Finds the next attachment of the email message.    /// </summary>    /// <returns>The ID of the next attachment if it was found; otherwise - 0.</returns>    procedure Attachments_Next(): Integer    begin        exit(EmailMessageImpl.Attachments_Next());    end;    /// <summary>    /// Gets the Id of the current attachment    /// </summary>    /// <returns>The ID of the current attachment.</returns>    procedure Attachments_GetId(): BigInteger    begin        exit(EmailMessageImpl.Attachments_GetId());    end;    /// <summary>    /// Gets the name of the current attachment.    /// </summary>    /// <returns>The name of the current attachment.</returns>    procedure Attachments_GetName(): Text[250]    begin        exit(EmailMessageImpl.Attachments_GetName());    end;    /// <summary>    /// Gets the content of the current attachment.    /// </summary>    /// <param name="AttachmentInStream">Out parameter with the content of the current attachment.</param>    procedure Attachments_GetContent(var AttachmentInStream: InStream)    begin        EmailMessageImpl.Attachments_GetContent(AttachmentInStream);    end;    /// <summary>    /// Gets the content of the current attachment in Base64 encoding.    /// </summary>    /// <returns>The content of the current attachment in Base64 encoding.</returns>    procedure Attachments_GetContentBase64(): Text    begin        exit(EmailMessageImpl.Attachments_GetContentBase64());    end;    /// <summary>    /// Gets the content type of the current attachment.    /// </summary>    /// <returns>The content type of the current attachment.</returns>    procedure Attachments_GetContentType(): Text[250]    begin        exit(EmailMessageImpl.Attachments_GetContentType());    end;    /// <summary>    /// Gets the content ID of the current attachment.    /// </summary>    /// <returns>The content ID of the current attachment.</returns>    /// <remarks>This value is filled only if the attachment is inline the email body.</remarks>    procedure Attachments_GetContentId(): Text[40]    begin        exit(EmailMessageImpl.Attachments_GetContentId());    end;    /// <summary>    /// Gets the content length of the current attachment.    /// </summary>    /// <returns>The content length of the current attachment.</returns>    procedure Attachments_GetLength(): Integer    begin        exit(EmailMessageImpl.Attachments_GetLength());    end;    /// <summary>    /// Checks if the attachment is inline the message body.    /// </summary>    /// <returns>True if the attachment is inline the message body; otherwise - false.</returns>    procedure Attachments_IsInline(): Boolean    begin        exit(EmailMessageImpl.Attachments_IsInline());    end;    /// <summary>    /// Gets the related attachments.    /// </summary>    /// <param name="EmailRelatedAttachments">Out parameter with the related attachments.</param>    /// <returns>True if any related attachments were found; otherwise - false</returns>    procedure GetRelatedAttachments(var EmailRelatedAttachments: Record "Email Related Attachment"): Boolean    begin        exit(EmailMessageImpl.GetRelatedAttachments(EmailRelatedAttachments));    end;    /// <summary>    /// Gets number of modifies on the message.    /// </summary>    /// <returns>The number of modifies.</returns>    internal procedure GetNoOfModifies(): Integer    begin        exit(EmailMessageImpl.GetNoOfModifies());    end;    /// <summary>    /// Integration event to provide the stream of data for a given MediaID. If attachment content has been deleted, this event makes it possible to provide    /// the data from elsewhere.    /// </summary>    /// <param name="MediaID">Id of the underlying media field that contains the attachment data.</param>    /// <param name="InStream">Stream to that should pointed to the attachment data.</param>    /// <param name="Handled">Was the attachment content added to the stream.</param>    [IntegrationEvent(false, false)]    internal procedure OnGetAttachmentContent(MediaID: Guid; var InStream: InStream; var Handled: Boolean)    begin    end;    var        EmailMessageImpl: Codeunit "Email Message Impl.";}