Golang package that generates clean, responsive HTML e-mails for sending transactional mail
Golang package that generates clean, responsive HTML e-mails for sending transactional mail
Hermes is the Go port of the great mailgen engine for Node.js. Check their work, it's awesome! It's a package that generates clean, responsive HTML e-mails for sending transactional e-mails (welcome e-mails, reset password e-mails, receipt e-mails and so on), and associated plain text fallback.
First install the package:
go get github.com/matcornic/[email protected]
v2 to v1.3.0At the time of v2 creation, Go modules logic and best practices were still unsure. v1 did not use modules.
Having a dedicated v2 module is meant to be used for projects hosting and maintaining v1 and v2 at the same time, so people can use both versions at the same time. There is no need for that in this kind of project.
Now that go modules usage is standard, in v1, starting from v1.3.0 tags, we decided to migrate back to github.com/matcornic/hermes instead of github.com/matcornic/hermes/v2.
v2 tags will still use github.com/matcornic/hermes/v2 as the import path, normal way will use github.com/matcornic/hermes as the import path.
So, just replace your import path from github.com/matcornic/hermes/v2 to github.com/matcornic/hermes and run go get github.com/matcornic/[email protected] (or newer) to update the dependency.
Then, start using the package by importing and configuring it:
// Configure hermes by setting a theme and your product info
h := hermes.Hermes{
// Optional Theme
// Theme: new(Default)
Product: hermes.Product{
// Appears in header & footer of e-mails
Name: "Hermes",
Link: "https://example-hermes.com/",
// Optional product logo
Logo: "http://www.duchess-france.org/wp-content/uploads/2016/01/gopher.png",
},
}
Next, generate an e-mail using the following code:
…
This code would output the following HTML template:
And the following plain text:
------------
Hi Jon Snow,
------------
Welcome to Hermes! We're very excited to have you on board.
To get started with Hermes, please click here: https://hermes-example.com/confirm?token=d9729feb74992cc3482b350163a1a010
Need help, or have questions? Just reply to this email, we'd love to help.
Yours truly,
Hermes - https://example-hermes.com/
Copyright © 2025 Hermes. All rights reserved.
Theme templates will be embedded in your application binary. If you want to use external templates (for configuration), use your own theme by implementing
hermes.Themeinterface with code searching for your files.
To run the examples, go to examples folder, then run go run -a *.go. HTML and Plaintext example should be created in given theme folders.
Optionaly you can set the following variables to send automatically the emails to one your mailbox. Nice for testing template in real email clients.
HERMES_SEND_EMAILS=trueHERMES_SMTP_SERVER=<smtp_server> : for Gmail it's smtp.gmail.comHERMES_SMTP_PORT=<smtp_port> : for Gmail it's 465HERMES_SENDER_EMAIL=<your_sender_email>HERMES_SENDER_IDENTITY=<the sender name>HERMES_SMTP_USER=<smtp user> : usually the same than HERMES_SENDER_EMAILHERMES_TO=<recipients emails>: split by commas like [email protected],[email protected]The program will ask for your SMTP password. If needed, you can set it with HERMES_SMTP_PASSWORD variable (but be careful where you put this information !)
To generate a plaintext version of the e-mail, simply call GeneratePlainText function:
// Generate plaintext email using hermes
emailText, err := h.GeneratePlainText(email)
if err != nil {
panic(err) // Tip: Handle error with something else than a panic ;)
}
The following open-source themes are bundled with this package:
default by Postmark Transactional Email Templates
flat, slightly modified from Postmark Transactional Email Templates
To change the default text direction (left-to-right), simply override it as follows:
// Configure hermes by setting a theme and your product info
h := hermes.Hermes {
// Custom text direction
TextDirection: hermes.TDRightToLeft,
}
To customize the e-mail's greeting ("Hi") or signature ("Yours truly"), supply custom strings within the e-mail's Body:
email := hermes.Email{
Body: hermes.Body{
Greeting: "Dear",
Signature: "Sincerely",
},
}
To use a custom title string rather than a greeting/name introduction, provide it instead of Name:
email := hermes.Email{
Body: hermes.Body{
// Title will override `Name`
Title: "Welcome to Hermes",
},
}
To customize the Copyright, override it when initializing Hermes within your Product as follows:
// Configure hermes by setting a theme and your product info
h := hermes.Hermes{
// Optional Theme
// Theme: new(Default)
Product: hermes.Product{
// Appears in header & footer of e-mails
Name: "Hermes",
Link: "https://example-hermes.com/",
// Custom copyright notice
Copyright: "Copyright © 2025 Dharma Initiative. All rights reserved."
},
}
To use a custom fallback text at the end of the email, change the TroubleText field of the hermes.Product struct. The default value is If you’re having trouble with the button '{ACTION}', copy and paste the URL below into your web browser.. The {ACTION} placeholder will be replaced with the corresponding text of the supplied action button:
// Configure hermes by setting a theme and your product info
h := hermes.Hermes{
// Optional Theme
// Theme: new(Default)
Product: hermes.Product{
// Custom trouble text
TroubleText: "If the {ACTION}-button is not working for you, just copy and paste the URL below into your web browser."
},
}
Since v2.1.0, Hermes is automatically inlining all CSS to improve compatibility with email clients, thanks to Premailer.
You can disable this feature by setting DisableCSSInlining of Hermes struct to true.
h := hermes.Hermes{
...
DisableCSSInlining: true,
}
Hermes supports injecting custom elements such as dictionaries, tables and action buttons into e-mails.
To inject an action button in to the e-mail, supply the Actions object as follows:
email := hermes.Email{
Body: hermes.Body{
Actions: []hermes.Action{
{
Instructions: "To get started with Hermes, please click here:",
Button: hermes.Button{
Color: "#22BC66", // Optional action button color
Text: "Confirm your account",
Link: "https://hermes-example.com/confirm?token=d9729feb74992cc3482b350163a1a010",
},
},
},
},
}
Alternatively, instead of having a button, an action can be an invite code as follows:
email := hermes.Email{
Body: hermes.Body{
Actions: []hermes.Action{
{
Instructions: "To get started with Hermes, please use the invite code:",
InviteCode: "123456",
},
},
},
}
To inject multiple action buttons in to the e-mail, supply another struct in Actions slice Action.
To inject a table into the e-mail, supply the Table object as follows:
…
To inject key-value pairs of data into the e-mail, supply the Dictionary object as follows:
email := hermes.Email{
Body: hermes.Body{
Dictionary: []hermes.Entry{
{Key: "Date", Value: "20 November 1887"},
{Key: "Address", Value: "221B Baker Street, London"},
},
},
}
If you need more flexibility in the content of your generated e-mail, while keeping the same format than any other e-mail, use Markdown content. Supply the FreeMarkdown object as follows:
email := hermes.Email{
Body: hermes.Body{
FreeMarkdown: `
> _Hermes_ service will shutdown the **1st August 2025** for maintenance operations.
Services will be unavailable based on the following schedule:
| Services | Downtime |
| :------:| :-----------: |
| Service A | 2AM to 3AM |
| Service B | 4AM to 5AM |
| Service C | 5AM to 6AM |
---
Feel free to contact us for any question regarding this matter at [[email protected]](mailto:[email protected]) or in our [Gitter](https://gitter.im/)
`,
},
}
}
This code would output the following HTML template:
And the following plaintext:
…
Be aware that this content will replace existing tables, dictionary and actions. Only intros, outros, header and footer will be kept.
This is helpful when your application needs sending e-mails, wrote on-the-fly by adminstrators.
Markdown is rendered with Blackfriday, so every thing Blackfriday can do, Hermes can do it as well.
Simply sending the
X-Entity-Ref-IDheader with your e-mails will prevent grouping / truncation.
See CONTRIBUTING.md
Apache 2.0
No open issues yet, or sync has not completed.