feat: allow setting sent date on APPEND

[mblarsen]

References issue #60

Followed syntax of (date-time token) http://www.faqs.org/rfcs/rfc3501.html

I followed the pattern of append calling append_with_flags calling append_with_flags_and_date.

• existing tests passes
• update fn docs

---

This change is 

[mblarsen]

I tested the implementation on a small tool to migrate a massive mbox file through imap on fastmail.com. Emails appear with expected times.

There's no test for append so I was lazy and didn't add to it.

So yeah, ready for review @jonhoo :)

[jonhoo]

Excellent, thank you! I left one small inline comment, but that's the only thing. It would be very nice to have an append test, but I'm not going to require it :p

[mblarsen]

Excellent, thank you! I left one small inline comment, but that's the only thing. It would be very nice to have an append test, but I'm not going to require it :p

Oh, my mistake hadn't seen the integration tests. I've added a test for the _and_date variant now.

However, I had to disable it for now since the date returned from Greenmail is the time of the append not the date given. The date you specify with APPEND is the internal date as far as I know. I'm not sure how to best test this as the returned envelop would have the sent date not the internal date.

I guess I could send to emails first one without _and_date then one with that has a date in the past, then do a fetch of them. I would assume the latter would be the first if it works.

Any thoughts?

[mblarsen]

Greenmail seems to be doing things by the book:
https://github.com/greenmail-mail-test/greenmail/blob/567046758010524c7382393fc0f740b8b4073e08/greenmail-core/src/main/java/com/icegreen/greenmail/imap/commands/AppendCommand.java#L42-L67

[jonhoo]

That's interesting -- if it doesn't modify the actual message date, how then is append with a date useful in practice? Can you extract it from the other fields of the message that aren't in the envelope?

Also, I had another thought over the weekend: I think this append API is getting pretty unwieldy. Given that we're going to be doing a breaking release soon anyway, I suggest we just make append be a single function that takes impl Into<AppendOptions> where

struct AppendOptions<'a> {
    flags: Option<&'a [Flag<'a>]>,
    date: Option<DateTime<FixedOffset>>,
}

And then have a couple of nice Into implementations for AppendOption. What do you think?

[mblarsen]

That's interesting -- if it doesn't modify the actual message date, how then is append with a date useful in practice? Can you extract it from the other fields of the message that aren't in the envelope?

Yes, that was it. Fetch has internal_date and with that in play the tests pass.

date updated to Into<Option<...>> as you suggested.

---

The AppendOption change makes sense to me. I can make that in a separate PR as it would break the current API as far as I can tell.

You also mentioned (somewhere) that you take the path of a builder. Would the you then create an AppendCmd that implements AppendOption so that user can use the builder or AppendOption directly?

session.append(
  mbox,
  e.message_to_string().unwrap(),
  AppendCmd::new()
     .flag("\Seen")
     .internal_date(&date)
);

Or did you think to have a more generic command builder that was fed to something like session.execute(..)?

[jonhoo]

Ah, yes, AppendCmd looks like a great idea! And a separate PR makes sense :)