improve comments

smtpserver/reputation.go

@@ -35,22 +35,23 @@ const (
 //
 // The decision is made based on historic messages delivered to the same
 // destination mailbox, MailboxOrigID. Because each mailbox may have a different
-// accept policy, for example mailing lists with an SPF mailfrom allow. We only use
+// accept policy. We only use messages that have been marked as either junk or
-// messages that have been marked as read. We expect users to mark junk messages as
+// non-junk. We help users by automatically marking them as non-junk when moving to
-// such when they read it. And to keep it in their inbox, regular trash or archive
+// certain folders in the default config (e.g. the archive folder). We expect users
-// if it is not.
+// to mark junk messages as such when they read it. And to keep it in their inbox,
+// regular trash or archive if it is not.
 //
 // The basic idea is to keep accepting messages that were accepted in the past, and
 // keep rejecting those that were rejected. This is relatively easy to check if
 // mail passes SPF and/or DKIM with Message-From alignment. Regular email from
-// known people will be let in. But spammers are trickier. They will use new
+// known people will be let in. But spammers are trickier. They will use new IPs,
 // (sub)domains, no or newly created SPF and/or DKIM identifiers, new localparts,
 // etc. This function likely ends up returning "inconclusive" for such emails. The
 // junkfilter will have to take care of a final decision.
 //
 // In case of doubt, it doesn't hurt much to accept another mail that a user has
 // communicated successfully with in the past. If the most recent message is marked
-// as junk that could have happened accidental. If another message is let in, and
+// as junk that could have happened accidentally. If another message is let in, and
 // it is again junk, future messages will be rejected.
 //
 // Actual spammers will probably try to use identifiers, i.e. (sub)domain, dkim/spf
@@ -59,34 +60,35 @@ const (
 //
 // Some profiles of first-time senders:
 //
-// - Individuals. They can typically get past the junkfilter if needed.
+//   - Individuals. They can typically get past the junkfilter if needed.
-// - Transaction emails. They should get past the junkfilter. If they use one of
+//   - Transactional emails. They should get past the junkfilter. If they use one of
-// the larger email service providers, their reputation could help. If the
+//     the larger email service providers, their reputation could help. If the
-// junkfilter rejects the message, users can recover the message from the Rejects
+//     junkfilter rejects the message, users can recover the message from the Rejects
-// mailbox. The first message is typically initiated by a user, e.g. by registering.
+//     mailbox. The first message is typically initiated by a user, e.g. by registering.
-// - Desired commercial email will have to get past the junkfilter based on its
+//   - Desired commercial email will have to get past the junkfilter based on its
-// content. There will typically be earlier communication with the (organizational)
+//     content. There will typically be earlier communication with the (organizational)
-// domain that would let the message through.
+//     domain that would let the message through.
-// - Mailing list. May get past the junkfilter. If delivery is to a separate
+//   - Mailing list. May get past the junkfilter. If delivery is to a separate
-// mailbox, the junkfilter will let it in because of little history. Long enough to
+//     mailbox, the junkfilter will let it in because of little history. Long enough to
-// build reputation based on DKIM/SPF signals.
+//     build reputation based on DKIM/SPF signals. Users are best off to
+//     configure accept rules for messages from mailing lists.
 //
 // The decision-making process looks at historic messages. The following properties
 // are checked until matching messages are found. If they are found, a decision is
 // returned, which may be inconclusive. The next property on the list is only
 // checked if a step did not match any messages.
 //
-// - Messages matching full "message from" address, either with strict/relaxed
+//   - Messages matching full "message from" address, either with strict/relaxed
-// dkim/spf-verification, or without.
+//     dkim/spf-verification, or without.
-// - Messages the user sent to the "message from" address.
+//   - Messages the user sent to the "message from" address.
-// - Messages matching only the domain of the "message from" address (different
+//   - Messages matching only the domain of the "message from" address (different
-// localpart), again with verification or without.
+//     localpart), again with verification or without.
-// - Messages sent to an address in the domain of the "message from" address.
+//   - Messages sent to an address in the domain of the "message from" address.
-// - The previous two checks again, but now checking against the organizational
+//   - The previous two checks again, but now checking against the organizational
-// domain instead of the exact domain.
+//     domain instead of the exact domain.
-// - Matching DKIM domains and a matching SPF mailfrom, or mailfrom domain, or ehlo
+//   - Matching DKIM domains and a matching SPF mailfrom, or mailfrom domain, or ehlo
-// domain.
+//     domain.
-// - "Exact" IP, or nearby IPs (/24 or /48).
+//   - "Exact" IP, or nearby IPs.
 //
 // References:
 // ../rfc/5863

store/account.go

@@ -364,9 +364,9 @@ func (m *Message) JunkFlagsForMailbox(mailbox string, conf config.Account) {
 // first-time incoming replies from users this account has sent messages to. On
 // IMAP append to Sent, the message is parsed and recipients are inserted as
 // recipient. Recipients are never removed other than for removing the message. On
-// IMAP move/copy, recipients aren't modified either. don't modify anything either.
+// IMAP move/copy, recipients aren't modified either. This assumes an IMAP client
-// This works by the assumption that an IMAP client simply appends messages to the
+// simply appends messages to the Sent mailbox (as opposed to copying messages from
-// Sent mailbox (as opposed to copying messages from some place).
+// some place).
 type Recipient struct {
 	ID        int64
 	MessageID int64          `bstore:"nonzero,ref Message"` // Ref gives it its own index, useful for fast removal as well.