= Bounce Handling =

Handle bounced email addresses in Launchpad.

'''Contact:''' GaryPoster <<BR>>
'''On Launchpad:''' Bug:341927

== Rationale ==

From the critical bug filed by James Troup:

  Right now mail sent from Launchpad is sent from 'bounces@canonical.com'.
  Any replies or bounces to this address are simply routed into /dev/null.
  This means that we never notice if we're sending mail to addresses that
  no longer exist or are over quota or any other failure mode. This makes
  our sending behaviour look "spam-ish" to the larger mail providers as
  they see us repeatedly sending mail to people who, from their
  perspective, they've asked us not to send mail to any more.

== Stakeholders ==

James Troup <james.troup@canonical.com> (James reviewed this Friday, July 29 2011.  From #launchpad-ops: "the LEP looks good to me")

LOSAs

GSAs

== User stories ==

<<Anchor(story-name>)>>

As a user I want to be be able to address problems with communicating to me via Launchpad so that I can receive the timely notifications I want.

As a Canonical SA I want mail providers to not regard Canonical's email as spam (because Launchpad ignores bounce communications) so that SAs do not have to spend time convincing mail providers that they should actually deliver our mail.

== Constraints and Requirements ==

=== Must ===

User Experience

 * We send normal Launchpad emails to each user's preferred email address, as we do now.
 * If a preferred email address bounces "too much" for our heuristics (as informed by Barry's Mailman experience), then we do the following.
   * We move the user's account into a state that means that their preferred email address is disabled.  In this document, call this the DISABLED PREFERRED EMAIL state.  We'll describe what this state means to the user below.
   * We send an email to all of that users' registered & validated email addresses, including the one that has bounced, informing them that their preferred email address has a problem.  Describe the symptoms and how to address the problem (see below for details on both).
 * As long as a user is the DISABLED PREFERRED EMAIL state (that is, as long as a user's preferred email address is disabled), we do the following.
   * We do not send any normal Launchpad emails to this user.
   * When a user views their registered email addresses, they can see what addresses have been disabled due to bounces, and reenable them, in addition to setting preferred email and adding and removing addresses, as they can do now.  Reenabling their preferred email address (and thereby leaving the DISABLED PREFERRED EMAIL state) can be done by changing their preferred email address to an address that is not disabled, or by declaring that their current email address should not be disabled.  Re-enabling an email address resets its bounce email heuristic score (described below).
   * We draw a red banner at the top of every web page rendered for this user.  The banner informs them of the problem and links to the page with their registered email addresses, as described immediately above, so they can address the problem.
   * Starting a week later after entering the DISABLED PREFERRED EMAIL state, we send out an email once a week for up to four weeks to the preferred email address, telling the user of the problem and linking to the page with their registered email addresses, so they can address the problem.  In this document, call this a PROBE email.
 * Launchpad (not Registry) administrators (https://launchpad.net/~admins) can change the disabled status of users' email addresses, and thereby affect the DISABLED PREFERRED EMAIL state.

Background and heuristics, as strongly informed by Mailman

[Arbitrary values in the below will be configurable, at a minimum by changing constants in a well-known place in the sourcecode.  These arbitrary values are indicated with italics.]

 * Bounces can be classified as permanent or temporary.  We effectively ignore temporary bounces.
 * Bounces can be caused by receiving bounce emails, or by getting SMTP errors when sending.  Barry's flufl.bounce library is responsible for identifying and classifying bounce emails as permanent or temporary, as well as identifying the affected email addresses.  For SMTP errors, the 450 code and 5xx codes can be regarded as permanent failures, and the other 400 codes can be regarded as temporary failures (see http://tools.ietf.org/html/rfc5321#section-4.2).
 * Each email address has a bounce score.  An unknown/good email address begins with a score of zero.  A score of *five* indicates that the address should be disabled.  A permanent bounce (email or smtp error) causes an address' bounce score to increase by one.  A given bounce score can only increase by one for any given *24 hour* period, so subsequent permanent bounces for the same address within that period are effectively ignored.
 * The bounce score for a given address is reset to zero if the address has not had a bounce for *seven days* and the address is not above the "disabled" threshold.
 * Re-enabling an email address resets the bounce score to zero.

=== Nice to have ===

 * If a user is in the DISABLED PREFERRED EMAIL state, this is visible to other Launchpad users, such as in bug subscription lists.  See also the "Holiday" display request in Bug:44542.
 * When a user views their email addresses, they see an indication if their preferred email address has had some recent bounce problems that have not yet led to disabling.
 * Let a user see the full text (including headers) of the most recent bounce from each of their emails.
 * Pay extra attention when a PROBE email: if it bounces, then it means...something in addition?  See Mailman Bug:808821.
 * Make a clear link that says "really, just stop sending me mail" by disabling the account or putting the account in "holiday" mode or something.

=== Must not ===

Explode.

=== Out of scope ===

This could make implementing the vacation/holiday feature request Bug:44542 really easy: it would be a similar state except that it would not send out the PROBE or initial warning emails.

== Subfeatures ==

None.

== Success ==

=== How will we know when we are done? ===

Launchpad does not send email to addresses that have bounced enough for us to consider them dead.

=== How will we measure how well we have done? ===

The rate of bounce messages we receive decreases dramatically because we are actually acting on them.  (Note that we still need to know what our current rate is.)

== Thoughts? ==

=== UI Mockups needed ===

 * Changes to email management page (https://launchpad.net/~/+editemails) showing display of disabled email addresses, controls to change the disabled state, and generally how we help a user get out of the DISABLED PREFERRED EMAIL state. (This is the same page that Launchpad admins use.)
 * Red banner on the top of every page describing the problem and linking to https://launchpad.net/~/+editemails.

=== Implementation proposal ===

The LEP intends to focus only on the user-visible description.  See [[ LEP/BounceHandling/Implementation | the implementation proposal ]] as it develops.