Interface IPostmasterService

Namespace

Tharga.Team

Assembly

Tharga.Team.dll

The postmaster: mail that reached the shared mailbox at an address no team owns.

public interface IPostmasterService

Remarks

Wholly system-wide. Unrouted mail belongs to no team, so only a system scope can govern it, and nothing a team holds reaches it.

Opening is the audited act. A listing shows sender, subject and time only; reading a mail that may hold another team's material is recorded every time, whatever the host's default audit mode.

Held or archived. A mail waits to be routed to a team or archived. Archiving puts it away without delivering it anywhere — spam, a mail sent by mistake, one dealt with elsewhere — and restoring brings it back. Either way it stays the postmaster's until the retention period deletes it.

Methods

ArchiveAsync(string, CancellationToken)

Puts a held mail away without delivering it to any team, recording when and by whom; null when the postmaster holds no mail by this id, which includes one already routed.

[RequireScope("mailbox:postmaster:manage", Audit = AuditMode.Change)]
Task<InboundMailItem> ArchiveAsync(string mailId, CancellationToken cancellationToken = default)

Parameters

mailId string

cancellationToken CancellationToken

Returns

Task<InboundMailItem>

Remarks

The mail leaves the held list and the count, is listed as Archived, and can still be opened, restored and routed. Archiving an archived mail returns it unchanged.

GetBodyAsync(string, CancellationToken)

An unrouted mail made readable — its text, its formatting sanitized, the images it shows in place and the files it carries — or null when the postmaster holds none by this id or its content is no longer kept.

[RequireScope("mailbox:postmaster:read", Audit = AuditMode.Access)]
Task<ReceivedMailBody> GetBodyAsync(string mailId, CancellationToken cancellationToken = default)

Parameters

mailId string

cancellationToken CancellationToken

Returns

Task<ReceivedMailBody>

Remarks

Read from the content GetContentAsync(string, CancellationToken) returns, for a reader that cannot parse a mail itself.

GetContentAsync(string, CancellationToken)

An unrouted mail as it arrived, or null when the postmaster holds none by this id.

[RequireScope("mailbox:postmaster:read", Audit = AuditMode.Access)]
Task<MailContent> GetContentAsync(string mailId, CancellationToken cancellationToken = default)

Parameters

mailId string

cancellationToken CancellationToken

Returns

Task<MailContent>

GetCountAsync(CancellationToken)

How much unrouted mail is held, archived mail left out.

[RequireScope("mailbox:postmaster:read")]
Task<int> GetCountAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Returns

Task<int>

ListAsync(string, int, CancellationToken)

A page of the mail the postmaster holds, archived mail left out, newest first.

[RequireScope("mailbox:postmaster:read")]
Task<PostmasterPage> ListAsync(string cursor = null, int pageSize = 50, CancellationToken cancellationToken = default)

Parameters

cursor string

pageSize int

cancellationToken CancellationToken

Returns

Task<PostmasterPage>

ListAsync(PostmasterMailState, string, int, CancellationToken)

A page of the postmaster's mail in one state, the most recently received first.

[RequireScope("mailbox:postmaster:read")]
Task<PostmasterPage> ListAsync(PostmasterMailState state, string cursor = null, int pageSize = 50, CancellationToken cancellationToken = default)

Parameters

state PostmasterMailState

cursor string

pageSize int

cancellationToken CancellationToken

Returns

Task<PostmasterPage>

Remarks

Archived mail is listed in the order it arrived, as held mail is, not in the order it was archived; each summary says when it was archived and by whom.

OpenAsync(string, CancellationToken)

One unrouted mail, held or archived, or null when the postmaster holds none by this id.

[RequireScope("mailbox:postmaster:read", Audit = AuditMode.Access)]
Task<InboundMailItem> OpenAsync(string mailId, CancellationToken cancellationToken = default)

Parameters

mailId string

cancellationToken CancellationToken

Returns

Task<InboundMailItem>

OpenAttachmentAsync(string, string, CancellationToken)

One file of an unrouted mail, by its id in Attachments, for the caller to dispose; null when the postmaster holds no such mail or the mail carries no such file.

[RequireScope("mailbox:postmaster:read", Audit = AuditMode.Access)]
Task<SupportAttachmentContent> OpenAttachmentAsync(string mailId, string attachmentId, CancellationToken cancellationToken = default)

Parameters

mailId string

attachmentId string

cancellationToken CancellationToken

Returns

Task<SupportAttachmentContent>

Remarks

Opening a file is opening the mail, so it is recorded the same way. Serve it as ServedAs(string) says, never as the type its sender declared.

RestoreAsync(string, CancellationToken)

Brings an archived mail back among the held mail; null when the postmaster holds no mail by this id. Restoring a held mail returns it unchanged.

[RequireScope("mailbox:postmaster:manage", Audit = AuditMode.Change)]
Task<InboundMailItem> RestoreAsync(string mailId, CancellationToken cancellationToken = default)

Parameters

mailId string

cancellationToken CancellationToken

Returns

Task<InboundMailItem>

RouteAsync(string, string, CancellationToken)

Delivers an unrouted mail to a team, marked as rerouted.

[RequireScope("mailbox:postmaster:manage", Audit = AuditMode.Change)]
Task<InboundMailItem> RouteAsync(string mailId, string toTeamKey, CancellationToken cancellationToken = default)

Parameters

mailId string

toTeamKey string

cancellationToken CancellationToken

Returns

Task<InboundMailItem>

Remarks

The team is where the mail goes, not who is asking: routing is authorized by the system scope alone, and the receiving team's grants play no part — which is why the parameter is not the teamKey a team service takes. An archived mail can be routed too, and arrives unhandled like any other.