From a8e110afaf8a8b96c3a3036da14c1aee9d5d1c42 Mon Sep 17 00:00:00 2001 From: Ivan Akimov Date: Tue, 27 Feb 2024 10:29:05 -0600 Subject: [PATCH] readme --- NUGET-README.md | 4 +- README.md | 200 ++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 187 insertions(+), 17 deletions(-) diff --git a/NUGET-README.md b/NUGET-README.md index d83108c..9d30445 100644 --- a/NUGET-README.md +++ b/NUGET-README.md @@ -97,8 +97,8 @@ Note: - Have suggestions or want to give feedback? Here's how to reach us: - - For feature requests, please [start a discussion](https://github.com/templateless/templateless-rust/discussions) - - Found a bug? [Open an issue!](https://github.com/templateless/templateless-rust/issues) + - For feature requests, please [start a discussion](https://github.com/templateless/templateless-dotnet/discussions) + - Found a bug? [Open an issue!](https://github.com/templateless/templateless-dotnet/issues) - We are also on Twitter: [@Templateless](https://twitter.com/templateless) ## 🍻 License diff --git a/README.md b/README.md index a5f37bc..c85a06a 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ [Templateless](https://templateless.com) lets you generate and send transactional emails quickly and easily so you can focus on building your product. +It's perfect for SaaS, web apps, mobile apps, scripts and anywhere you have to send email programmatically. + ## ✨ Features - 👋 **Anti drag-and-drop by design** — emails are a part of your code @@ -48,6 +50,16 @@ Alternatively, using the .NET CLI: dotnet add package Templateless ``` +## 🔑 Get Your API Key + +You'll need an API key for the example below ⬇️ + +[![Get Your API Key](https://img.shields.io/badge/Get_Your_API_Key-free-blue?style=for-the-badge)](https://app.templateless.com/) + +- 3,000 emails per month +- All popular email provider integrations +- Start sending right away + ## 👩‍💻 Quick example This is all it takes to send a signup confirmation email: @@ -91,24 +103,182 @@ class Program } ``` -> **Note** -> 🚧 **This SDK is not stable yet.** The API might change as more features are added. Please pay attention to the [CHANGELOG](CHANGELOG.md) for breaking changes. +There are more C# examples in the [examples](examples) folder ✨ + +> [!NOTE] +> 🚧 **The SDK is not stable yet.** This API might change as more features are added. Please watch the repo for the changes in the [CHANGELOG](CHANGELOG.md). + +## 🔳 Components + +Emails are crafted programmatically by making function calls. There's no dealing with HTML or drag-and-drop builders. + +All of the following components can be mixed and matched to create dynamic emails: + +
+ Text / Markdown + +Text component allow you to insert a paragraph. Each paragraph supports basic markdown: + +- Bold text: `**bold text**` +- Italic text: `_italic text_` +- Link: `[link text](https://example.com)` +- Also a link: `` +- Headers (h1-h6): + + - `# Big Header` + - `###### Small Header` + +```cs +Content.Builder() + .Text("## Thank you for signing up") + .Text("Please **verify your email** by [clicking here](https://example.com/confirm?token=XYZ)") + .Build(); +``` + +
+
Link + +Link component adds an anchor tag. This is the same as a text component with the link written in markdown: + +```cs +Content.Builder() + .Link("Confirm Email", "https://example.com/confirm?token=XYZ") // or... + .Text("[Confirm Email](https://example.com/confirm?token=XYZ)") + .Build(); +``` + +
+
Button + +Button can also be used as a call to action. Button color is set via your dashboard's app color. + +```cs +Content.Builder() + .Button("Confirm Email", "https://example.com/confirm?token=XYZ") + .Build(); +``` + +
+
Image + +Image component will link to an image within your email. Keep in mind that a lot of email clients will prevent images from being loaded automatically for privacy reasons. + +```cs +Content.Builder() + .Image( + "https://placekitten.com/300/200", // where the image is hosted + "https://example.com", // [optional] link url, if you want it to be clickable + 300, // [optional] width + 200, // [optional] height + "Alt text" // [optional] alternate text + ) + .Build(); +``` + +Only the `src` parameter is required; everything else is optional. + +**If you have "Image Optimization" turned on:** + +1. Your images will be cached and distributed by our CDN for faster loading. The cache does not expire. If you'd like to re-cache, simply append a query parameter to the end of your image url. +1. Images will be converted into formats that are widely supported by email clients. The following image formats will be processed automatically: + + - Jpeg + - Png + - Gif + - WebP + - Tiff + - Ico + - Bmp + - Svg + +1. Maximum image size is 5MB for free accounts and 20MB for paid accounts. +1. You can specify `width` and/or `height` if you'd like (they are optional). Keep in mind that images will be scaled down to fit within the email theme, if they're too large. + +
+
One-Time Password + +OTP component is designed for showing temporary passwords and reset codes. + +```cs +Content.Builder() + .Text("Here's your **temporary login code**:") + .Otp("XY78-2BT0-YFNB-ALW9") + .Build(); +``` + +
+
Social Icons + +You can easily add social icons with links by simply specifying the username. Usually, this component is placed in the footer of the email. -Examples: +These are all the supported platforms: + +```cs +Content.Builder() + .Socials(new List + { + new SocialItem(Service.Website, "https://example.com"), + new SocialItem(Service.Email, "username@example.com"), + new SocialItem(Service.Phone, "123-456-7890"), // `tel:` link + new SocialItem(Service.Facebook, "Username"), + new SocialItem(Service.YouTube, "ChannelID"), + new SocialItem(Service.Twitter, "Username"), + new SocialItem(Service.X, "Username"), + new SocialItem(Service.GitHub, "Username"), + new SocialItem(Service.Instagram, "Username"), + new SocialItem(Service.LinkedIn, "Username"), + new SocialItem(Service.Slack, "Org"), + new SocialItem(Service.Discord, "Username"), + new SocialItem(Service.TikTok, "Username"), + new SocialItem(Service.Snapchat, "Username"), + new SocialItem(Service.Threads, "Username"), + new SocialItem(Service.Telegram, "Username") + }) + .Build(); +``` -1. Get your **free API key** here: ✨ -1. There are more C# examples in the [examples](examples) folder: +
+
View in Browser - ```bash - TEMPLATELESS_API_KEY= \ - TEMPLATELESS_EMAIL_ADDRESS= \ - dotnet run --project ./examples/SimpleExample/SimpleExample.csproj - ``` +If you'd like your recipients to be able to read the email in a browser, you can add the "view in browser" component that will automatically generate a link. Usually, this is placed in the header or footer of the email. + +You can optionally provide the text for the link. If none is provided, default is used: "View in browser" + +**This will make the email public to anyone that has access to the link.** + +```cs +Content.Builder() + .ViewInBrowser("Read Email in Browser") + .Build(); +``` + +
+ +Components can be placed in the header, body and footer of the email. Header and footer styling is usually a bit different from the body (for example the text is smaller). + +```cs +var header = Header.Builder() // header of the email + .Text("Smaller text") + .Build(); + +var content = Content.Builder() // body of the email + .Text("Normal text") + .Build(); +``` + +Currently there are 2 themes to choose from: `Theme.Unstyled` and `Theme.Simple` + +```cs +var content = Content.Builder() + .Theme(Theme.Simple) + .Text("Hello world") + .Build(); +``` ## 🤝 Contributing -- Contributions are more than welcome <3 -- Please **star this repo** for more visibility ★ +- Contributions are more than welcome +- Please **star this repo** for more visibility <3 ## 📫 Get in touch @@ -116,9 +286,9 @@ Examples: - Have suggestions or want to give feedback? Here's how to reach us: - - For feature requests, please [start a discussion](https://github.com/templateless/templateless-rust/discussions) - - Found a bug? [Open an issue!](https://github.com/templateless/templateless-rust/issues) - - We are also on Twitter: [@Templateless](https://twitter.com/templateless) + - For feature requests, please [start a discussion](https://github.com/templateless/templateless-dotnet/discussions) + - Found a bug? [Open an issue!](https://github.com/templateless/templateless-dotnet/issues) + - Say hi [@Templateless](https://twitter.com/templateless) 👋 ## 🍻 License