The patch is a reasonable effort, thanks.  However, before we can really evaluate any code, we need to agree on an API.

The Message object presents a hybrid dictionary/sequence API over the headers.  In the Sequence API, we insert something into the list using 'insert(pos, object)`.  dict has no 'insert' method, so we don't need to worry about an API clash there.

So we could define the method insert_header to have the following signature:

  insert_header(pos, name, value)

add_header is still required, because we can't use insert_header to append.  (It would then be nice if it were named append_header...but ignore that for now).

However, there is almost no other context in which one interacts with the header list via a header's index in the list of headers.  Message does not support the 'index' method.

An alternate API, then, might be something like:

    insert_header_after(existing_name, new_name, value)

This would be analogous to replace_header.

The trouble with this, and the trouble with defining a header_index, is that multiple headers can have the same name.  Message's answer to this currently is to have both a 'get' method and a 'get_all' method.  The former returns the first match, the latter all of them.

The reason this matters, by the way, is that one of the motivations for insert_header in my mind is the ability to create a sensible flow of headers: have the routing and forwarding headers (received, resent-xxx, etc) headers be before the From/to/date, etc headers.  But to do that, you need to be able to insert them *after* the other headers with the same name.

You could make 'insert after last instance of name' the default behavior of insert_header_after, but then we sill don't have a way to insert a header in an arbitrary location.

Another possibility is 'insert_header' combined with both 'header_index' and 'header_index_all'.

I *think* I'm leaning toward the latter (with my biggest hesitation being that insert_header is pretty much the only place you can use the index information returned by the index methods), but this kind of API design issue is something we should run by the email-sig mailing list.  Feel free to post something there yourself, otherwise I will do so after I finish the 'whatsnew' work.