Interface IUserMessageService
- Namespace
- Tharga.Team
- Assembly
- Tharga.Team.dll
Messages the product's staff write to chosen users of its teams, and the log of every message sent; every member requires the system scope Send.
public interface IUserMessageServiceRemarks
Gated: registered as a system service, so a call without the scope is refused before it reaches the implementation and the refusal is audited. Sending and reading the log are audited by the service itself, with counts and never addresses, so the per-call access trace is turned off.
Methods
GetAddresseesAsync(UserMessageRecipients, string, int, int, CancellationToken)
One page of the users the selection reaches, ordered by name, each with the address the mail would go to, their teams, whether the filter selected them or they were added, and whether they turned the category off; the totals are PreviewAsync(UserMessageRecipients, string, CancellationToken)'s and the users are those SendAsync(UserMessage, CancellationToken) would queue.
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<UserMessageAddresseePage> GetAddresseesAsync(UserMessageRecipients recipients, string category, int skip = 0, int take = 50, CancellationToken cancellationToken = default)Parameters
recipientsUserMessageRecipientscategorystringskipinttakeintcancellationTokenCancellationToken
Returns
Remarks
At most 100 users a page; not audited, as reading the counts and searching are not.
Exceptions
- ArgumentException
The selection names neither teams nor users, or the category is not one staff may write in.
GetChoicesAsync(CancellationToken)
The teams, roles, access levels and categories a message may be written to and in, and the limits it is held to; users are found with SearchUsersAsync(UserMessageUserSearch, CancellationToken).
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<UserMessageChoices> GetChoicesAsync(CancellationToken cancellationToken = default)Parameters
cancellationTokenCancellationToken
Returns
GetRecipientsAsync(string, UserMailStatus?, string, int, CancellationToken)
One page of a sent message's recipients in the order they were queued, each with the address it went to and what became of it, only those in status when one is given; null when there is no message with this id.
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<UserMessageRecipientPage> GetRecipientsAsync(string messageId, UserMailStatus? status = null, string cursor = null, int pageSize = 50, CancellationToken cancellationToken = default)Parameters
messageIdstringstatusUserMailStatus?cursorstringpageSizeintcancellationTokenCancellationToken
Returns
Exceptions
- ArgumentException
The cursor was not issued for this list.
GetSentAsync(string, int, CancellationToken)
One page of the sent log, newest first, with each message's outcome counts.
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<SentUserMessagePage> GetSentAsync(string cursor = null, int pageSize = 20, CancellationToken cancellationToken = default)Parameters
cursorstringpageSizeintcancellationTokenCancellationToken
Returns
GetSentMessageAsync(string, CancellationToken)
One sent message with its outcome counts and why each mail given up was, or null when there is none with this id.
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<SentUserMessage> GetSentMessageAsync(string messageId, CancellationToken cancellationToken = default)Parameters
messageIdstringcancellationTokenCancellationToken
Returns
PreviewAsync(UserMessageRecipients, string, CancellationToken)
How many users the selection reaches and how many of them turned the category off, counts only.
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<UserMessagePreview> PreviewAsync(UserMessageRecipients recipients, string category, CancellationToken cancellationToken = default)Parameters
recipientsUserMessageRecipientscategorystringcancellationTokenCancellationToken
Returns
Exceptions
- ArgumentException
The selection names neither teams nor users, or the category is not one staff may write in.
PreviewMailAsync(UserMessage, CancellationToken)
The message as a recipient would receive it — sender, subject, the body in the host's template, and the footer with an unsubscribe line for an optional category — rendered without sending or storing anything.
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<MailPreview> PreviewMailAsync(UserMessage message, CancellationToken cancellationToken = default)Parameters
messageUserMessagecancellationTokenCancellationToken
Returns
Remarks
The selection is not read, and the unsubscribe link in it unsubscribes nobody; files are not rendered.
Exceptions
- ArgumentException
The category is not one staff may write in.
SearchUsersAsync(UserMessageUserSearch, CancellationToken)
At most Limit active members of the chosen teams, or of every team, whose name or address holds the text, each once with the teams they are active in; none for empty text.
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<UserMessageCandidate[]> SearchUsersAsync(UserMessageUserSearch search, CancellationToken cancellationToken = default)Parameters
searchUserMessageUserSearchcancellationTokenCancellationToken
Returns
SendAsync(UserMessage, CancellationToken)
Queues one mail per user the selection reaches, returns at once with the message as the log records it, and audits the send.
[RequireScope("messages:send", Audit = AuditMode.None)]
Task<SentUserMessage> SendAsync(UserMessage message, CancellationToken cancellationToken = default)Parameters
messageUserMessagecancellationTokenCancellationToken
Returns
Exceptions
- ArgumentException
The selection names neither teams nor users or reaches nobody, the category is not one staff may write in, or the message has no subject or body or exceeds the limits.