SMTP Docs - mentioning how to set up Subject and Body in SendMail

[dowl...@gmail.com]

This has been an increasing frustration in the GO docs when there are assumptions as to what a programmer knows. Just recently I was working with the net/smtp package and no where in the package did it mention how to set up subject and body for smtp.Sendmail() 

http://golang.org/pkg/net/smtp/

I finally found one way of doing with with []byte("Subject: Test Subject  \r\n\r\n Test Email Body")

I understand this information is in the SMTP RFC: https://www.ietf.org/rfc/rfc2821.txt 

but it wouldn't hurt to add extra information like that to help a GO programmer looking for a quick reference. 

I love this language and want it to be more widely adopted but I find many that are new to the language struggling to understand the docs. Something Ruby does incredibly well is have detailed and well thought out documentation on everything. Simply a suggestion on all of us doing better with documentation when it comes to GOLang

Thanks,

Jiran

[Brad Fitzpatrick]

File a bug https://github.com/golang/go/issues for this and I'll get it fixed for Go 1.5.

This package is pretty low-level and assumes you know SMTP, but since we have the higher-level SendMail function, we might as well document it a bit better.

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Mateusz Czapliński]

On Wednesday, February 4, 2015 at 11:28:48 PM UTC+1, dowl...@gmail.com wrote:

This has been an increasing frustration in the GO docs when there are assumptions as to what a programmer knows. Just recently I was working with the net/smtp package and no where in the package did it mention how to set up subject and body for smtp.Sendmail() 

http://golang.org/pkg/net/smtp/

I finally found one way of doing with with []byte("Subject: Test Subject  \r\n\r\n Test Email Body")

I understand this information is in the SMTP RFC: https://www.ietf.org/rfc/rfc2821.txt

You should have a look at:
    https://github.com/go-gomail/gomail
It seems the best of Go SMTP libraries I could find when doing some tests recently.

/Mateusz.

[Jiran Dowlati]

Oh awesome didn't know this one existed, it looks really nice.

Thanks for the heads up! 

Jiran

--

Jiran Dowlati

720.318.9888

[Mateusz Czapliński]

On Wednesday, February 11, 2015 at 6:03:24 AM UTC+1, Jiran Dowlati wrote:

Oh awesome didn't know this one existed, it looks really nice.

By the way, if you don't know it yet, http://go-search.org/ is indispensable for me when researching Go libraries.

/M.

[Konstantin Khomoutov]

There's an entrenched misconseption about what SMTP is.
Some libraries for popular programming languages (starting with PHP and
its mail() function) tried to blur the distinction between constructing
an e-mail message (what the MIME set of RFCs deals with) and sending it
to an SMTP server. The latter is a protocol for message *exchange,* and
it does no assumptions about what it transfers until that data is
properly formatted (SMTP is an ASCII-based protocol, so there are
concepts of lines, end-of-line sequences, maximum line length and the
way to signal to the server the data stream is over). You can use SMTP
to transfer anything which fits, with SOAP payloads being one popular
example (in the past).

I understand your frustration with the problem at hand, but Go is not
to blame here. In the light of what I explained, if we're to put
explanatory material on SMTP vs MIME in the smtp package docs, by the
same rule, we'll also need to discuss stream-oriented I/O in the io
package docs, discuss the semantics of datagrams when presenting the
functions for working with UDP in the net package and so on and so on.
Clearly, this is out of the scope of reference material.

So please read some background introductory material on MIME and SMTP,
and it will greatly help you to understand why the smtp package is
organised the way it is.

[Marvin Renich]

* Konstantin Khomoutov <flat...@users.sourceforge.net> [150211 05:49]:

> There's an entrenched misconseption about what SMTP is.
> Some libraries for popular programming languages (starting with PHP and
> its mail() function) tried to blur the distinction between constructing
> an e-mail message (what the MIME set of RFCs deals with) and sending it
> to an SMTP server. The latter is a protocol for message *exchange,* and
> it does no assumptions about what it transfers until that data is
> properly formatted (SMTP is an ASCII-based protocol, so there are
> concepts of lines, end-of-line sequences, maximum line length and the
> way to signal to the server the data stream is over). You can use SMTP
> to transfer anything which fits, with SOAP payloads being one popular
> example (in the past).
>
> I understand your frustration with the problem at hand, but Go is not
> to blame here. In the light of what I explained, if we're to put
> explanatory material on SMTP vs MIME in the smtp package docs, by the
> same rule, we'll also need to discuss stream-oriented I/O in the io
> package docs, discuss the semantics of datagrams when presenting the
> functions for working with UDP in the net package and so on and so on.
> Clearly, this is out of the scope of reference material.

That's all well and good, but for both the SMTP protocol and the Go
net/smtp package, 99.999% of the use case is to send email. Extending
the package example to add the very basic headers expected in most email
messages is not only not unreasonable, but, IMHO, very desirable.

Your attempted correlation between extending an existing example in the
smtp package to include typical usage and adding technical info on
specific aspects of the io and net packages makes no sense.

You also have to consider the expected users of the package when
documenting. The users of the smtp package are less likely to
understand the distinction between email transfer protocol and email
content than the users of ListenUDP are likely to understand the
semantics of datagrams.

...Marvin