Essentials: Email API's

[mattleibow]

A simple API to send an email.

static class Email {
    static bool IsAttachmentSupported { get; }
    static bool IsHtmlMessageSupported { get; }

    // should throw a NotSupportedOnDeviceException if the device is not capable.
    Task ComposeAsync(EmailMessage message);

class EmailMessage {
    EmailMessage(string subject, string body, params string[] to);

    string Subject { get; set }
    string Body { get; set }
    bool IsMessageHtml { get; set }
    IList<string> To  { get; set; }
    IList<string> Bcc { get; set; }
    IList<string> Cc { get; set; }
    IList<EmailAttachment> Attachments { get; set; }

    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, Stream stream);
    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, string filename);
    // should throw a NotSupportedOnDeviceException if the device is not capable.
    void Attach(string attachmentName, string contentType, byte[] data);
}

class EmailAttachment {
    string Name { get; set; }
    string ContentType { get; set; }
    string FileName { get; set; }
    Stream Stream { get; set; }
}

For the discussion around exceptions, see #19

[mattleibow]

We should check to see if platforms can support streams or data chunks. We could throw, or we could save to a temporary file.

[Redth]

I believe they all support streams, and if they support streams, you can MemoryStream a byte[]. I don't think this will be an issue.

I'm still not quite happy with EmailAttachment... I think we should try and get rid of FileName, at least as a _public_ property.

[jamesmontemagno]

I would also say I am pretty cool with Attachments not making v1 :)

[alanag13]

should this include a method to open the constructed email in the device's default client (similar to if the user had clicked a mailto link)?

[Redth]

Updated the original issue with a bit different of API. EmailMessage is now a separate class with all of the options for sending an email. Email is now a static class to send messages and check capabilities.

[Redth]

@alanag13 what are device capabilities like here? Do all the platforms generally support both sending an email without user intervention as well as 'opening' the email up on their device to send?

[alanag13]

@redth I assumed sending was supported on all relevant devices since that's what this spec seems to imply. I know that "open" is supported on both iOS and Android because I have done this. On UWP I haven't personally done this but I feel like I've used applications where I had this experience. I'd have to look at little closer for that platform in particular.

[alanag13]

@redth seems like it would be something like this: https://docs.microsoft.com/en-us/windows/uwp/contacts-and-calendar/sending-email#launch-the-compose-email-dialog

[alanag13]

@redth actually, unless I'm missing something, some quick googling suggests that on most of these platforms sending an email programmatically without user intervention on the default client isn't possible with the API unless you authenticate to an SMTP server and such... so i'm thinking SendAsync should be LaunchMailClientAsync or something

[Redth]

Yep, I think the confusion here is that Send in this case is really Compose. I've updated the original issue to be ComposeAsync which all the current target platforms seem to support.

[Redth]

We've got someone internally working on this. PR will be up shortly with progress.

[ephraimf]

How can I use Email.ComposeAsync to send an attachment?

[mattleibow]

@ephraimf This is tracked here: https://github.com/xamarin/Essentials/issues/130 and here: https://github.com/xamarin/Essentials/pull/416