Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alexgaribay/sendgrid_elixir
Create and send composable emails with Elixir and SendGrid.
https://github.com/alexgaribay/sendgrid_elixir
Last synced: about 2 months ago
JSON representation
Create and send composable emails with Elixir and SendGrid.
- Host: GitHub
- URL: https://github.com/alexgaribay/sendgrid_elixir
- Owner: alexgaribay
- License: mit
- Created: 2016-02-28T18:30:25.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-04-12T19:35:16.000Z (8 months ago)
- Last Synced: 2024-10-14T15:35:38.623Z (about 2 months ago)
- Language: Elixir
- Homepage:
- Size: 87.9 KB
- Stars: 86
- Watchers: 4
- Forks: 44
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- freaking_awesome_elixir - Elixir - Send composable, transactional emails with SendGrid. (Third Party APIs)
- fucking-awesome-elixir - sendgrid - Send composable, transactional emails with SendGrid. (Third Party APIs)
- awesome-elixir - sendgrid - Send composable, transactional emails with SendGrid. (Third Party APIs)
README
# SendGrid
A wrapper for SendGrid's API to create composable emails.
Check the [docs](https://hexdocs.pm/sendgrid/) for complete usage.
## Example
```elixir
SendGrid.Email.build()
|> SendGrid.Email.add_to("[email protected]")
|> SendGrid.Email.put_from("[email protected]")
|> SendGrid.Email.put_subject("Hello from Elixir")
|> SendGrid.Email.put_text("Sent with Elixir")
|> SendGrid.Mail.send()
```
## Installation
Add the following code to your dependencies in your **`mix.exs`** file:
```elixir
{:sendgrid, "~> 2.0"}
```
## Configuration
In one of your configuration files, include your SendGrid API key like this:
```elixir
config :sendgrid,
api_key: "SENDGRID_API_KEY"
```
If you want to use environment variable, use `{:system, "ENV_NAME"}` in your config:
```elixir
config :sendgrid,
api_key: {:system, "SENDGRID_API_KEY"}
```
If you'd like to enable sandbox mode (emails won't send but will be validated), add the setting to your config:
```elixir
config :sendgrid,
api_key: "SENDGRID_API_KEY",
sandbox_enable: true
```
Add `:sendgrid` to your list of applications if using Elixir 1.3 or lower.
```elixir
defp application do
[applications: [:sendgrid]]
end
```
## Phoenix Views
You can use Phoenix Views to set your HTML and text content of your emails. You just have
to provide a view module and template name and you're good to go! Additionally, you can set
a layout to render the view in with `SendGrid.Email.put_phoenix_layout/2`. See `SendGrid.Email.put_phoenix_template/3`
for complete usage.
### Examples
```elixir
import SendGrid.Email
# Using an HTML template
%SendGrid.Email{}
|> put_phoenix_view(MyApp.Web.EmailView)
|> put_phoenix_template("welcome_email.html", user: user)
# Using a text template
%SendGrid.Email{}
|> put_phoenix_view(MyApp.Web.EmailView)
|> put_phoenix_template("welcome_email.txt", user: user)
# Using both an HTML and text template
%SendGrid.Email{}
|> put_phoenix_view(MyApp.Web.EmailView)
|> put_phoenix_template(:welcome_email, user: user)
# Setting the layout
%SendGrid.Email{}
|> put_phoenix_layout({MyApp.Web.EmailView, :layout})
|> put_phoenix_view(MyApp.Web.EmailView)
|> put_phoenix_template(:welcome_email, user: user)
```
### Using a Default Phoenix View
You can set a default Phoenix View to use for rendering templates. Just set the `:phoenix_view` config value
```elixir
config :sendgrid,
phoenix_view: MyApp.Web.EmailView
```
### Using a Default Layout
You can set a default layout to render your view in. Set the `:phoenix_layout` config value.
```elixir
config :sendgrid,
phoenix_layout: {MyApp.Web.EmailView, :layout}
```
## Personalizations
Personalizations are used to identify who should receive the email as well as specifics about how you would like the email to be handled.
Personalizations allow you to define:
- `to`, `cc`, `bcc` - The recipients of your email.
- `subject` - The subject of your email.
- `headers` - Any headers you would like to include in your email.
- `substitutions` - Any substitutions you would like to be made for your email.
- `custom_args` - Any custom arguments you would like to include in your email.
- `dynamic_template_data` - Data to send along with a template.
- `send_at` - A specific time that you would like your email to be sent.
An `SendGrid.Email` automatically takes these fields and transforms them into a personalization to be sent in the email. However, you can add multiple personalizations to an email and specify different handling instructions for different copies of your email. For example, you could send the same email to both and , but set each email to be delivered at different times.
### Example
```elixir
alias SendGrid.{Mail, Email}
personalization_1 =
Email.build()
|> Email.add_to("[email protected]")
|> Email.put_subject("Exciting news!")
|> Email.to_personalization()
personalization_2 =
Email.build()
|> Email.add_to("[email protected]")
|> Email.put_subject("We've some exciting news!")
|> Email.to_personalization()
Email.build()
|> Email.put_from("[email protected]")
|> Email.put_text("...")
|> Email.put_html("...")
|> Email.add_personalization(personalization_1)
|> Email.add_personalization(personalization_2)
|> Mail.send()
```
### Limitations
The SendGrid v3 API limits you to 1,000 personalizations per API request. If you need to include more than 1,000 personalizations, please divide these across multiple API requests.
## Testing
To run the unit tests you will need to create a `config/config.exs` file and provide your own SendGrid API and email address to receive a test email.
```elixir
use Mix.Config
config :sendgrid,
api_key: "",
phoenix_view: SendGrid.Email.Test.EmailView,
test_address: "[email protected]"
```
The `config` directory is excluded from the git repository so your API key and email address will not be committed.
Once configured you can run the full test suite including integration tests as follows:
```console
mix test --include integration
```