README
¶
Blackmail is a Go package to send emails.
Current status: work-in-progress. Most of it works, but the API isn't stable yet and some things are not yet implemented as documented.
Why a new package? I didn't care much for the API of many of the existing solutions.
Import the library as zgo.at/blackmail; API docs: https://godocs.io/zgo.at/blackmail
There is also a smtp client library at zgo.at/blackmail/smtp which can be used
without the main blackmail client if you want. It's a modified version of
net/smtp (via go-smtp, although I removed most added features from
that).
There is a small commandline utility at cmd/blackmail; try it with go run ./cmd/blackmail.
The main use case where you just want to send off an email and be done with it. Non-goals include things like parsing email messages, support for encodings other than ASCII and UTF-8, or a one-stop-shop for your very specific complex requirements. It should be able to handle all common (and not-so-common) use cases though.
Example
// Send a new message using blackmail.DefaultMailer
err := blackmail.Send("Send me bitcoins or I will leak your browsing history!",
blackmail.From("", "blackmail@example.com"),
blackmail.To("Name", "victim@example.com"),
blackmail.Bodyf("I can haz ur bitcoinz?"))
// A more complex message with a text and HTML part and inline image.
err = blackmail.Send("I saw what you did last night 😏",
blackmail.From("😏", "blackmail@example.com"),
append(blackmail.To("Name", "victim@example.com"), blackmail.Cc("Other", "other@example.com")...),
blackmail.Text("Text part")
blackmail.HTML("HTML part: <img src="cid:blackmail:1">",
blackmail.InlineImage("image/png", "logo.png", imgbytes)))
// You can create your own (re-usable) mailer.
mailer := blackmail.NewMailer("smtp://user:pass@localhost:25")
err = mailer.Send([..])
// Add some options to your mailer.
mailer = blackmail.NewMailer("smtp://user:pass@localhost:25
blackmail.MailerAuth(..),
blackmail.MailerTLS(&tls.Config{}),
blackmail.RequireSTARTLS(true))
// Get RF5322 message with a list of recipients to send it to (To + Cc + Bcc).
msg, to := blackmail.Message([.. same arguments as Send() ..])
See the test cases in blackmail_test.go for various
other examples.
Questions you may have
I get the error "tls: first record does not look like a TLS handshake"
You are attempting to establish a TLS connection to a server which doesn't
support TLS or only supports it via the STARTTLS command.
I get the error "x509: certificate signed by unknown authority"
The certificate chain used for the TLS connection is not signed by a known authority. It's a self-signed certificate or you don't have the root certificates installed.
How can I use a @ in my username?
Encode as %40:
smtp://carpetsmoker%40fastmail.nl:PASS@smtp.fastmail.com:587'
Dedication
I first had the idea of blackmail well over 10 years ago after seeing some Joe Armstrong interview where he mentioned he or a co-worker (I forgot) maintained an email client in the 80s blackmail. I rewrote my PHP "mailview" webmail client to Python years ago and called it blackmail, but never finished or released it.
Finally, after all these years I have a change to steal use the blackmail
name for an email-related thing!
This package is dedicated to Joe Armstrong. I never programmed Erlang, but found many of his writings and talks insightful, and – more importantly – he was a funny guy.
…and now for the tricky bit…
Documentation
¶
Overview ¶
Package blackmail sends emails.
Index ¶
- Constants
- Variables
- func Attachment(contentType, filename string, body []byte) bodyPart
- func Bcc(addr ...string) []recipient
- func BccAddress(addr ...mail.Address) []recipient
- func BccNames(nameAddr ...string) []recipient
- func Body(contentType string, body []byte) bodyPart
- func BodyHTML(body []byte, images ...bodyPart) bodyPart
- func BodyMust(contentType string, fn func() ([]byte, error)) bodyPart
- func BodyMustHTML(fn func() ([]byte, error)) bodyPart
- func BodyMustText(fn func() ([]byte, error)) bodyPart
- func BodyText(body []byte) bodyPart
- func Bodyf(s string, args ...interface{}) bodyPart
- func Cc(addr ...string) []recipient
- func CcAddress(addr ...mail.Address) []recipient
- func CcNames(nameAddr ...string) []recipient
- func From(name, address string) mail.Address
- func Headers(keyValue ...string) bodyPart
- func HeadersAutoreply() bodyPart
- func InlineImage(contentType, filename string, body []byte) bodyPart
- func MailerAuth(v string) senderOpt
- func MailerOut(v io.Writer) senderOpt
- func MailerRequireTLS(v bool) senderOpt
- func MailerTLS(v *tls.Config) senderOpt
- func Message(subject string, from mail.Address, rcpt []recipient, firstPart bodyPart, ...) ([]byte, []string, error)
- func NopCloser(r io.Writer) io.WriteCloser
- func Send(subject string, from mail.Address, rcpt []recipient, firstPart bodyPart, ...) error
- func To(addr ...string) []recipient
- func ToAddress(addr ...mail.Address) []recipient
- func ToNames(nameAddr ...string) []recipient
- type Mailer
- type SoftError
Constants ¶
const ( ConnectWriter = "writer" // Write to an io.Writer. ConnectDirect = "direct" // Connect directly to MX records. )
const ( AuthLogin = "login" AuthPlain = "plain" AuthCramMD5 = "cram-md5" )
Authentication methods for MailerAuth().
Variables ¶
var DefaultMailer = NewMailer(ConnectDirect)
DefaultMailer is used with blackmail.Send().
Functions ¶
func Attachment ¶
Attachment returns a new attachment part with the given Content-Type.
It will try to guess the Content-Type if empty.
func BccAddress ¶
func BodyHTML ¶
func BodyHTML(body []byte, images ...bodyPart) bodyPart
BodyHTML returns a new text/html part.
func BodyMust ¶
BodyMust sets the body using a callback, propagating any errors back up.
This is useful when using Go templates for the mail body;
buf := new(bytes.Buffer)
err := tpl.ExecuteTemplate(buf, "email", struct{
Name string
}{"Martin"})
if err != nil {
log.Fatal(err)
}
err := Send("Basic test", From("", "me@example.com"),
To("to@to.to"),
Body("text/plain", buf.Bytes()))
With BodyMust(), it's simpler; you just need to define a little helper re-usable helper function and call that:
func template(tplname string, args interface{}) func() ([]byte, error) {
return func() ([]byte, error) {
buf := new(bytes.Buffer)
err := tpl.ExecuteTemplate(buf, tplname, args)
return buf.Bytes(), err
}
}
err := Send("Basic test", From("", "me@example.com"),
To("to@to.to"),
BodyMust("text/html", template("email", struct {
Name string
}{"Martin"})))
Other use cases include things like loading data from a file, reading from a stream, etc.
func BodyMustHTML ¶
BodyMustHTML is like BodyMust() with contentType text/html.
func BodyMustText ¶
BodyMustText is like BodyMust() with contentType text/plain.
func Bodyf ¶
func Bodyf(s string, args ...interface{}) bodyPart
Bodyf returns a new text/plain part.
func From ¶
From makes creating a mail.Address a bit more convenient.
mail.Address{Name: "foo, Address: "foo@example.com}
blackmail.From{"foo, "foo@example.com)
func Headers ¶
func Headers(keyValue ...string) bodyPart
Headers adds the headers to the message.
This will override any headers set automatically by the system, such as Date: or Message-Id:
Headers("My-Header", "value",
"Message-Id", "<my-message-id@example.com>")
func HeadersAutoreply ¶
func HeadersAutoreply() bodyPart
HeadersAutoreply sets headers to indicate this message is a an autoreply.
See e.g: https://www.arp242.net/autoreply.html#what-you-need-to-set-on-your-auto-response
func InlineImage ¶
InlineImage returns a new inline image part.
It will try to guess the Content-Type if empty.
Then use "cid:blackmail:<n>" to reference it:
<img src="cid:blackmail:1"> First InlineImage() <img src="cid:blackmail:2"> Second InlineImage()
func MailerAuth ¶
func MailerAuth(v string) senderOpt
MailerAuth sets the AUTH method for the relay mailer. Currently LOGIN, PLAIN, and CRAM-MD5 are supported.
In general, PLAIN is preferred and it's the default. Note that CRAM-MD5 only provides weak security over untrusted connections.
func MailerRequireTLS ¶
func MailerRequireTLS(v bool) senderOpt
MailerRequireTLS sets whether TLS is required.
func Message ¶
func Message(subject string, from mail.Address, rcpt []recipient, firstPart bodyPart, parts ...bodyPart) ([]byte, []string, error)
Message formats a message.
func Send ¶
func Send(subject string, from mail.Address, rcpt []recipient, firstPart bodyPart, parts ...bodyPart) error
Send an email using the DefaultMailer.
The arguments are identical to Message().
Types ¶
type Mailer ¶
type Mailer struct {
// contains filtered or unexported fields
}
Mailer to send messages; use NewMailer() to construct a new instance.
func NewMailer ¶
NewMailer returns a new re-usable mailer.
Setting the connection string to blackmail.Writer will print all messages to stdout without sending them:
NewMailer(blackmail.Writer)
You can pass Mailer.Writer() as an option to send them somewhere else:
NewMailer(blackmail.Writer, blackmail.MailerOut(os.Stderr)) buf := new(bytes.Buffer) NewMailer(blackmail.Writer, blackmail.MailerOut(buf))
If the connection string is set to blackmail.Direct, blackmail will look up the MX records and attempt to deliver to them.
NewMailer(blackmail.Direct)
Any URL will be used as a SMTP relay:
NewMailer("smtps://foo:foo@mail.foo.com")
The default authentication is PLAIN; add MailerAuth() to set something different.
Source Files
Directories