Codeunit 8904 Email Message
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.";}