{"id":13670063,"url":"https://github.com/ainsleyclark/go-mail","last_synced_at":"2025-04-07T07:14:44.811Z","repository":{"id":40667673,"uuid":"355873786","full_name":"ainsleyclark/go-mail","owner":"ainsleyclark","description":"📧 A cross platform mail driver for GoLang. Featuring Mailgun, Postal, Postmark, SendGrid, SparkPost \u0026 SMTP.","archived":false,"fork":false,"pushed_at":"2024-06-24T17:53:23.000Z","size":767,"stargazers_count":179,"open_issues_count":4,"forks_count":16,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-10-12T04:09:20.658Z","etag":null,"topics":["email","go","golang","mail","mailgun","postal","postmark","sendgrid","smtp","sparkpost"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ainsleyclark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ainsleyclark"]}},"created_at":"2021-04-08T11:08:51.000Z","updated_at":"2024-05-30T11:41:50.000Z","dependencies_parsed_at":"2024-05-28T22:29:09.123Z","dependency_job_id":"fd386b3c-f44c-4548-96af-c09fdf00a0f4","html_url":"https://github.com/ainsleyclark/go-mail","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Fgo-mail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Fgo-mail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Fgo-mail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ainsleyclark%2Fgo-mail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ainsleyclark","download_url":"https://codeload.github.com/ainsleyclark/go-mail/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608153,"owners_count":20965952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","go","golang","mail","mailgun","postal","postmark","sendgrid","smtp","sparkpost"],"created_at":"2024-08-02T09:00:31.188Z","updated_at":"2025-04-07T07:14:44.785Z","avatar_url":"https://github.com/ainsleyclark.png","language":"Go","funding_links":["https://github.com/sponsors/ainsleyclark"],"categories":["Go"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\u003cimg height=\"300\" src=\"res/logos/go-mail.svg?size=new2\" alt=\"Go Mail Logo\" /\u003e\n\n[![made-with-Go](https://img.shields.io/badge/Made%20with-Go-1f425f.svg)](http://golang.org)\n[![Go Report Card](https://goreportcard.com/badge/github.com/ainsleyclark/go-mail)](https://goreportcard.com/report/github.com/ainsleyclark/go-mail)\n[![Test](https://github.com/ainsleyclark/go-mail/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/ainsleyclark/go-mail/actions/workflows/test.yml)\n[![codecov](https://codecov.io/gh/ainsleyclark/go-mail/branch/main/graph/badge.svg?token=1ZI9R34CHQ)](https://codecov.io/gh/ainsleyclark/go-mail)\n[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white\u0026style=flat)](https://pkg.go.dev/github.com/ainsleyclark/go-mail)\n[![Twitter Handle](https://img.shields.io/twitter/follow/ainsleydev)](https://twitter.com/ainsleydev)\n\u003c/div\u003e\n\n# 📧 Go Mail\n\nA cross-platform mail driver for GoLang. Featuring Mailgun, Postal, Postmark, SendGrid, SparkPost \u0026 SMTP.\n\n## Overview\n\n- ✅ Multiple mail drivers for your needs or even create your own custom Mailer.\n- ✅ Direct dependency free, all requests are made with the standard lib http.Client.\n- ✅ Send attachments with two struct fields, it's extremely simple.\n- ✅ Send CC \u0026 BCC messages.\n- ✅ Extremely lightweight.\n\n## Supported API's\n\n- \u003cimg align=\"left\" src=\"res/logos/mailgun.svg\" width=\"24\" /\u003e  [Mailgun](https://documentation.mailgun.com/)\n\n- \u003cimg align=\"left\" src=\"res/logos/postal.svg\" width=\"24\" /\u003e [Postal](https://docs.postalserver.io/)\n\n- \u003cimg align=\"left\" src=\"res/logos/postmark.png\" width=\"24\" /\u003e [Postmark](https://postmarkapp.com/)\n\n- \u003cimg align=\"left\" src=\"res/logos/sendgrid.svg\" width=\"24\" /\u003e [SendGrid](https://sendgrid.com/)\n\n- \u003cimg align=\"left\" src=\"res/logos/sparkpost.png?new=new\" width=\"24\" /\u003e [SparkPost](https://www.sparkpost.com/)\n\n- \u003cimg align=\"left\" src=\"res/logos/smtp.svg\" width=\"24\" /\u003e SMTP\n\n## Introduction\n\nGo Mail aims to unify multiple popular mail APIs into a singular, easy to use interface. Email sending is seriously\nsimple and great for allowing the developer or end user to choose what platform they use.\n\n```go\ncfg := mail.Config{\n    URL:         \"https://api.eu.sparkpost.com\",\n    APIKey:      \"my-key\",\n    FromAddress: \"hello@gophers.com\",\n    FromName:    \"Gopher\",\n}\n\nmailer, err := drivers.NewSparkPost(cfg)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\ntx := \u0026mail.Transmission{\n    Recipients:  []string{\"hello@gophers.com\"},\n    Subject:     \"My email\",\n    HTML:        \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n}\n\nresult, err := mailer.Send(tx)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\nfmt.Printf(\"%+v\\n\", result)\n```\n\n## Installation\n\n```bash\ngo get -u github.com/ainsleyclark/go-mail\n```\n\n## Docs\n\nDocumentation can be found at the [Go Docs](https://pkg.go.dev/github.com/ainsleyclark/go-mail), but we have included a\nkick-start guide below to get you started.\n\n### Creating a new client:\n\nYou can create a new driver by calling the `drivers` package and passing in a configuration type which is required to\ncreate a new mailer. Each platform requires its own data, for example, Mailgun requires a domain, but SparkPost doesn't.\nThis is based of the requirements for the API. For more details see the [examples](#Examples) below.\n\n```go\ncfg := mail.Config{\n\tURL:         \"https://api.eu.sparkpost.com\",\n\tAPIKey:      \"my-key\",\n\tFromAddress: \"hello@gophers.com\",\n\tFromName:    \"Gopher\",\n\tClient:       http.DefaultClient, // Client is optional\n}\n\nmailer, err := drivers.NewSparkpost(cfg)\nif err != nil {\n\tlog.Fatalln(err)\n}\n```\n\n### Sending Data:\n\nA transmission is required to transmit to a mailer as shown below. Once send is called, a `mail.Response` and an `error`\nbe returned indicating if the transmission was successful.\n\n```go\ntx := \u0026mail.Transmission{\n\tRecipients: []string{\"hello@gophers.com\"},\n\tCC:         []string{\"cc@gophers.com\"},\n\tBCC:        []string{\"bcc@gophers.com\"},\n\tSubject:    \"My email\",\n\tHTML:       \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n\tPlainText:  \"Hello from Go Mail!\",\n\tHeaders: map[string]string{\n\t\t\"X-Go-Mail\": \"Test\",\n\t},\n}\n\nresult, err := mailer.Send(tx)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\nfmt.Printf(\"%+v\\n\", result)\n```\n\n### Response:\n\nThe mail response is used for debugging and inspecting results of the mailer. Below is the `Response` type.\n\n```go\n// Response represents the data passed back from a successful transmission.\ntype Response struct {\n\tStatusCode int         // e.g. 200\n\tBody       []byte      // e.g. {\"result: success\"}\n\tHeaders    http.Header // e.g. map[X-Ratelimit-Limit:[600]]\n\tID         string      // e.g \"100\"\n\tMessage    string      // e.g \"Email sent successfully\"\n}\n```\n\n### Adding attachments:\n\nAdding attachments to the transmission is as simple as passing a byte slice and filename. Go Mail takes care of the rest\nfor you.\n\n```go\nimage, err := ioutil.ReadFile(\"gopher.jpg\")\nif err != nil {\n\tlog.Fatalln(err)\n}\n\ntx := \u0026mail.Transmission{\n\tRecipients: []string{\"hello@gophers.com\"},\n\tSubject:    \"My email\",\n\tHTML:       \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n\tPlainText:  \"plain text\",\n\tAttachments: []mail.Attachment{\n\t\t{\n\t\t\tFilename: \"gopher.jpg\",\n\t\t\tBytes:    image,\n\t\t},\n\t},\n}\n```\n\n## Examples\n\n#### Mailgun\n\n```go\ncfg := mail.Config{\nURL:         \"https://api.eu.mailgun.net\", // Or https://api.mailgun.net\n\tAPIKey:      \"my-key\",\n\tFromAddress: \"hello@gophers.com\",\n\tFromName:    \"Gopher\",\n\tDomain:      \"my-domain.com\",\n}\n\nmailer, err := drivers.NewMailgun(cfg)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\ntx := \u0026mail.Transmission{\n\tRecipients: []string{\"hello@gophers.com\"},\n\tCC:         []string{\"cc@gophers.com\"},\n\tBCC:        []string{\"bcc@gophers.com\"},\n\tSubject:    \"My email\",\n\tHTML:       \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n\tPlainText:  \"Hello from Go Mail!\",\n}\n\nresult, err := mailer.Send(tx)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\nfmt.Printf(\"%+v\\n\", result)\n```\n\n#### Postal\n\n```go\ncfg := mail.Config{\n\tURL:         \"https://postal.example.com\",\n\tAPIKey:      \"my-key\",\n\tFromAddress: \"hello@gophers.com\",\n\tFromName:    \"Gopher\",\n}\n\nmailer, err := drivers.NewPostal(cfg)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\ntx := \u0026mail.Transmission{\n\tRecipients: []string{\"hello@gophers.com\"},\n\tCC:         []string{\"cc@gophers.com\"},\n\tBCC:        []string{\"bcc@gophers.com\"},\n\tSubject:    \"My email\",\n\tHTML:       \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n\tPlainText:  \"Hello from Go Mail!\",\n}\n\nresult, err := mailer.Send(tx)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\nfmt.Printf(\"%+v\\n\", result)\n```\n\n#### Postmark\n\n```go\ncfg := mail.Config{\n\tAPIKey:      \"my-key\",\n\tFromAddress: \"hello@gophers.com\",\n\tFromName:    \"Gopher\",\n}\n\nmailer, err := drivers.NewPostmark(cfg)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\ntx := \u0026mail.Transmission{\n\tRecipients: []string{\"hello@gophers.com\"},\n\tCC:         []string{\"cc@gophers.com\"},\n\tBCC:        []string{\"bcc@gophers.com\"},\n\tSubject:    \"My email\",\n\tHTML:       \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n\tPlainText:  \"Hello from Go Mail!\",\n}\n\nresult, err := mailer.Send(tx)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\nfmt.Printf(\"%+v\\n\", result)\n```\n\n#### SendGrid\n\n```go\ncfg := mail.Config{\n\tAPIKey:      \"my-key\",\n\tFromAddress: \"hello@gophers.com\",\n\tFromName:    \"Gopher\",\n}\n\nmailer, err := drivers.NewSendGrid(cfg)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\ntx := \u0026mail.Transmission{\n\tRecipients: []string{\"hello@gophers.com\"},\n\tCC:         []string{\"cc@gophers.com\"},\n\tBCC:        []string{\"bcc@gophers.com\"},\n\tSubject:    \"My email\",\n\tHTML:       \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n\tPlainText:  \"Hello from Go Mail!\",\n}\n\nresult, err := mailer.Send(tx)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\nfmt.Printf(\"%+v\\n\", result)\n```\n\n#### SMTP\n\n```go\ncfg := mail.Config{\n\tURL:         \"smtp.gmail.com\",\n\tFromAddress: \"hello@gophers.com\",\n\tFromName:    \"Gopher\",\n\tPassword:    \"my-password\",\n\tPort:        587,\n}\n\nmailer, err := drivers.NewSMTP(cfg)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\ntx := \u0026mail.Transmission{\n\tRecipients: []string{\"hello@gophers.com\"},\n\tCC:         []string{\"cc@gophers.com\"},\n\tBCC:        []string{\"bcc@gophers.com\"},\n\tSubject:    \"My email\",\n\tHTML:       \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n\tPlainText:  \"Hello from Go Mail!\",\n}\n\nresult, err := mailer.Send(tx)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\nfmt.Printf(\"%+v\\n\", result)\n```\n\n#### SparkPost\n\n```go\ncfg := mail.Config{\n\tURL:         \"https://api.eu.sparkpost.com\", // Or https://api.sparkpost.com/api/v1\n\tAPIKey:      \"my-key\",\n\tFromAddress: \"hello@gophers.com\",\n\tFromName:    \"Gopher\",\n}\n\nmailer, err := drivers.NewSparkPost(cfg)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\ntx := \u0026mail.Transmission{\n\tRecipients: []string{\"hello@gophers.com\"},\n\tCC:         []string{\"cc@gophers.com\"},\n\tBCC:        []string{\"bcc@gophers.com\"},\n\tSubject:    \"My email\",\n\tHTML:       \"\u003ch1\u003eHello from Go Mail!\u003c/h1\u003e\",\n\tPlainText:  \"Hello from Go Mail!\",\n}\n\nresult, err := mailer.Send(tx)\nif err != nil {\n\tlog.Fatalln(err)\n}\n\nfmt.Printf(\"%+v\\n\", result)\n```\n\n## Writing a Mailable\n\nYou have the ability to create your own custom Mailer by implementing the singular method interface shown below.\n\n```go\ntype Mailer interface {\n\t// Send accepts a mail.Transmission to send an email through a particular\n\t// driver/provider. Transmissions will be validated before sending.\n\t//\n\t// A mail.Response or an error will be returned. In some circumstances\n\t// the body and status code will be attached to the response for debugging.\n\tSend(t *mail.Transmission) (mail.Response, error)\n}\n```\n\n## Debugging\n\nTo debug any errors or issues you are facing with Go Mail, you are able to change the `Debug` variable in the\n`mail` package. This will write the HTTP requests in curl to stdout. Additional information will also be\ndisplayed in the errors such as method operations.\n\n```go\nmail.Debug = true\n```\n\n## Development\n\n### Setup\n\nTo get set up with Go Mail simply clone the repo and run the following:\n\n```bash\ngo get github.com/vektra/mockery/v2/.../\nmake setup\nmake mocks\n```\n\n## Env\n\nAll secrets are contained within the `.env` file for testing drivers. To begin with, make a copy of the `.env.example`\nfile and name it `.env`. You can the set the environment variables to match your credentials for the mail drivers.\n\nYou can set the recipients of emails by modifying the `EMAIL` variables as show below.\n\n- `EMAIL_TO`: Recipients of test emails in a comma delimited list.\n- `EMAIL_CC`: CC recipients of test emails in a comma delimited list.\n- `EMAIL_BCC`: BCC recipients of test emails in a comma delimited list.\n\n### Testing\n\nTo run all driver tests, execute the following command:\n\n```bash\nmake test-driver\n```\n\nTo run a specific driver test, prepend the `driver` flag as show below:\n\n```bash\nmake test-driver driver=sparkpost\n```\n\nThe driver flag can be one of the following:\n\n- `mailgun`\n- `postal`\n- `postmark`\n- `sendgrid`\n- `smtp`\n- `sparkpost`\n\n## Contributing\n\nWe welcome contributors, but please read the [contributing document](CONTRIBUTING.md) before making a pull request.\n\n## Credits\n\nShout out to the incredible [Maria Letta](https://github.com/MariaLetta) for her excellent Gopher illustrations.\n\n## Licence\n\nCode Copyright 2022 Go Mail. Code released under the [MIT Licence](LICENCE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fainsleyclark%2Fgo-mail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fainsleyclark%2Fgo-mail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fainsleyclark%2Fgo-mail/lists"}