https://github.com/vindarel/cl-sendgrid
Send emails with SendGrid's API
https://github.com/vindarel/cl-sendgrid
common-lisp email email-sender sendgrid sendgrid-api
Last synced: 6 months ago
JSON representation
Send emails with SendGrid's API
- Host: GitHub
- URL: https://github.com/vindarel/cl-sendgrid
- Owner: vindarel
- Created: 2020-04-21T10:56:44.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-18T15:03:55.000Z (almost 2 years ago)
- Last Synced: 2025-04-05T22:28:56.803Z (9 months ago)
- Topics: common-lisp, email, email-sender, sendgrid, sendgrid-api
- Language: Common Lisp
- Size: 52.7 KB
- Stars: 14
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
Awesome Lists containing this project
- awesome-cl - sendgrid - send emails with Sendgrid's API. [MIT][200]. (Interfaces to other package managers / Email)
README
# Send emails with the SendGrid API
https://sendgrid.com/
# Installation
On Quicklisp (2020-10):
(ql:quickload "sendgrid")
and on [Ultralisp](https://ultralisp.org/).
# Current usage (Please jump to [Updated usage](#updated-usage) to see upcoming changes)
Create a SendGrid account and set these variables:
```lisp
(setf *email-config*
'(:|api-key| "your private api key"
:|from| "the default 'from' address."))
```
Send an email with `send-email`:
```lisp
(sendgrid:send-email &key to
(from (getf *email-config* :|from|))
(reply-to (getf *email-config* :|reply-to|))
subject
content
(verbose *verbose*))
;; #()
;; 202
;; #
;; #
;; #>
```
It takes the time of a POST request.
# Updated usage
## API KEY
After obtaining an API key from [SendGrid](https://sendgrid.com/), you can either
### Provide the API key via an Operating System environment variable
```lisp
CL-USER> sendgrid:*api-key-environment-variable-name*
"SENDGRID_API_KEY" ; default environment variable name, you can change it.
```
Then you can do it by OS built-in facility, such as
```bash
export SENDGRID_API_KEY=your_sendgrid_api_key_value
```
Or set it using UIOP
```lisp
CL-USER> (setf (uiop:getenv sendgrid:*api-key-environment-variable-name*) your-api-key-value)
```
### Provide the API key when calling `sendgrid:send-mail`
`api-key` is one of the parameter of `sendgrid:send-mail`
```lisp
(sendgrid:send-email &rest rest
&key
to
from
subject
content
reply-to ; if not nil, should be an alist as (("email" . string) ("name" . string))
(content-type "text/plain")
(api-key (uiop:getenv *api-key-environment-variable-name*))
&allow-other-keys)
```
## Sample plain text email
### Minimum
```lisp
(sendgrid:send-email :to "recipient@example.com"
:from "noreply@example.com"
:subject "Sending emails from SendGrid is fun!"
:content "Sending emails from SendGrid is fun!")
```
### With `reply-to`
```lisp
(sendgrid:send-email :to "recipient@example.com"
:from "team@example.com"
:reply-to '(("email" . "noreply@example.com") ("name" . "No Reply"))
:subject "Sending emails from SendGrid is fun!"
:content "Sending emails from SendGrid is fun!")
```
## Sample HTML email
```lisp
(sendgrid:send-email :to "recipient@example.com"
:from "noreply@example.com"
:subject "Sending emails from SendGrid is fun!"
:content-type "text/html"
:content "
A title
Sending emails from SendGrid is fun!")
```
## Verbose mode example
```
(let ((sendgrid:*verbose* t))
(sendgrid:send-email :to "recipient@example.com"
:from "noreply@example.com"
:subject "Sending emails from SendGrid is fun!"
:content-type "text/html"
:content "A title
Sending emails from SendGrid is fun!"))
```
## Optional - Add sender name
Without a from name, your sending email will be the name of the email. Use the optional `:from-name` key to add a more appropriate sender name.
```lisp
(sendgrid:send-email :to "recipient@example.com"
:from "noreply@example.com"
:from-name "Jane Doe"
:subject "Sending emails from SendGrid is fun!"
:content-type "text/html"
:content "
A title
Sending emails from SendGrid is fun!")
```
## Email scheduling - :send-at key
The :send-at key takes a unix epoch time and sends your email at that specific time.
Free sendgrid accounts (at this time - 4th Oct 23) are limited to sending up to 3 days in the future. Therefore the `:send-at` key is limited to sending emails between 1-3 days in the future.
### Send email now
To send an email now, you can omit the `:send-at` key (see examples above).
### Send email in the future
Use the function `(now-plus-n-days n)` where `n` can be 1, 2, or 3 days in the future. This function will return the epoch time for that future date.
```lisp
(sendgrid:send-email :to "recipient@example.com"
:from "noreply@example.com"
:from-name "Jane Doe"
;; send email 2 days in the future
:send-at (now-plus-n-days 2)
:subject "Sending emails from SendGrid is fun!"
:content-type "text/html"
:content "
A title
Sending emails from SendGrid is fun!")
```
## Sending emails with .txt attachments
You can use the `:attachments` key to send attachments. Set attachments to `t` and then you can use the `:file` and `:filename` keys to provide your attachement.
`:file` takes the path to the txt file you want to attach.
`:filename` takes a string that represents the file name of the attachment.
Example:
```lisp
(sendgrid:send-email :to "recipient@example.com"
:from "noreply@example.com"
:from-name "Jane Doe"
:send-at (now-plus-n-days 2)
:subject "Sending emails from SendGrid is fun!"
:content-type "text/html"
:content "
A title
Sending emails from SendGrid is fun!"
:attachments t
:file "/path/to/txt/file"
:filename "filename.txt")
```
## Sending emails with `pdf` attachments
Ensure that the `:file` is a path to your pdf file and the `:filename` ends with `.pdf`.
Example:
```lisp
(sendgrid:send-email :to "recipient@example.com"
:from "noreply@example.com"
:from-name "Jane Doe"
:send-at (now-plus-n-days 2)
:subject "Sending emails from SendGrid is fun!"
:content-type "text/html" ;; this is the content type of the email, not the attachments.
:content "
A title
Sending emails from SendGrid is fun!"
:attachments t
:file "/path/to/txt/pdf/file"
:filename "filename.pdf")
```
You will receive an email with the attachment `filename.pdf`. The content of the file will match that of `/path/to/pdf/file`.
## Triggering email automations with add-contact-to-list
Inside sendgrid, if you navigate to Marketing --> Contacts, you can create a contact list. A contact list is a specific segment of people that did, or will do a specific action. For example, you can have a contact list for new subscribers to your product.
A list can have automatic actions attached to it. For example, you can trigger an email automation based on somebody subscribing to the list (This is managed in Marketing --> Automations).
With the `add-contact-to-list` function, you can add a single contact to a specifc contact list by using the list-id.
Note - you can find the list-id at the end of the contact list url. For example `https://mc.sendgrid.com/contacts/lists/ac32607e-e253-490b-a171-d84d88xxxxxx`, in this case `ac32607e-e253-490b-a171-d84d88xxxxxx` is the list id.
```lisp
(add-contact-to-list :email "vinn@kev.com"
:firstname "Vinn"
:list-id "ac32607e-e253-490b-a171-d84d88xxxxxx")
```
# See also
* https://github.com/40ants/mailgun (Mailgun: just a bit more overhead to getting started, a free plan a bit less free)
* https://github.com/CodyReichert/awesome-cl#email
* [spinneret](https://github.com/ruricolist/spinneret) (recommended) or [cl-who](https://edicl.github.io/cl-who/) for generating HTML strings.
# Licence
MIT.