1# Gomail
2[![Build Status](https://travis-ci.org/go-mail/mail.svg?branch=master)](https://travis-ci.org/go-mail/mail) [![Code Coverage](http://gocover.io/_badge/github.com/go-mail/mail)](http://gocover.io/github.com/go-mail/mail) [![Documentation](https://godoc.org/github.com/go-mail/mail?status.svg)](https://godoc.org/github.com/go-mail/mail)
3
4This is an actively maintained fork of [Gomail][1] and includes fixes and
5improvements for a number of outstanding issues. The current progress is
6as follows:
7
8 - [x] Timeouts and retries can be specified outside of the 10 second default.
9 - [x] Proxying is supported through specifying a custom [NetDialTimeout][2].
10 - [ ] Filenames are properly encoded for non-ASCII characters.
11 - [ ] Email addresses are properly encoded for non-ASCII characters.
12 - [ ] Embedded files and attachments are tested for their existence.
13 - [ ] An `io.Reader` can be supplied when embedding and attaching files.
14
15See [Transitioning Existing Codebases][3] for more information on switching.
16
17[1]: https://github.com/go-gomail/gomail
18[2]: https://godoc.org/gopkg.in/mail.v2#NetDialTimeout
19[3]: #transitioning-existing-codebases
20
21## Introduction
22
23Gomail is a simple and efficient package to send emails. It is well tested and
24documented.
25
26Gomail can only send emails using an SMTP server. But the API is flexible and it
27is easy to implement other methods for sending emails using a local Postfix, an
28API, etc.
29
30It requires Go 1.2 or newer. With Go 1.5, no external dependencies are used.
31
32
33## Features
34
35Gomail supports:
36- Attachments
37- Embedded images
38- HTML and text templates
39- Automatic encoding of special characters
40- SSL and TLS
41- Sending multiple emails with the same SMTP connection
42
43
44## Documentation
45
46https://godoc.org/github.com/go-mail/mail
47
48
49## Download
50
51If you're already using a dependency manager, like [dep][dep], use the following
52import path:
53
54```
55github.com/go-mail/mail
56```
57
58If you *aren't* using vendoring, `go get` the [Gopkg.in](http://gopkg.in)
59import path:
60
61```
62gopkg.in/mail.v2
63```
64
65[dep]: https://github.com/golang/dep#readme
66
67## Examples
68
69See the [examples in the documentation](https://godoc.org/github.com/go-mail/mail#example-package).
70
71
72## FAQ
73
74### x509: certificate signed by unknown authority
75
76If you get this error it means the certificate used by the SMTP server is not
77considered valid by the client running Gomail. As a quick workaround you can
78bypass the verification of the server's certificate chain and host name by using
79`SetTLSConfig`:
80
81```go
82package main
83
84import (
85	"crypto/tls"
86
87	"gopkg.in/mail.v2"
88)
89
90func main() {
91	d := mail.NewDialer("smtp.example.com", 587, "user", "123456")
92	d.TLSConfig = &tls.Config{InsecureSkipVerify: true}
93
94	// Send emails using d.
95}
96```
97
98Note, however, that this is insecure and should not be used in production.
99
100### Transitioning Existing Codebases
101
102If you're already using the original Gomail, switching is as easy as updating
103the import line to:
104
105```
106import gomail "gopkg.in/mail.v2"
107```
108
109## Contribute
110
111Contributions are more than welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for
112more info.
113
114
115## Change log
116
117See [CHANGELOG.md](CHANGELOG.md).
118
119
120## License
121
122[MIT](LICENSE)
123
124
125## Support & Contact
126
127You can ask questions on the [Gomail
128thread](https://groups.google.com/d/topic/golang-nuts/jMxZHzvvEVg/discussion)
129in the Go mailing-list.
130