The mailgun Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The mailgun Reference Manual

This is the mailgun Reference Manual, version 0.2.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:00:33 2021 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

=========================================
 mailgun - send emails from Common Lisp!
=========================================

.. Everything starting from this commit will be inserted into the
   index page of the HTML documentation.
.. include-from

This library provides an easy way to send transactional emails through
http://mailgun.com.

.. note:: You don't have to setup your own SMTP servers!

          And they have a "free" plan with 10000 emails per month.


Reasoning
=========

Previously, I used this code in one of my projects, but seems this
functionality needed almost in any serious web application. So, I
decided to make it available as a separate library.

Here is how to use it
=====================

First, setup an account at http://mailgun.com. You need to add your
domain there and to reveive an authentication token.

.. code-block:: common-lisp

   (setf mailgun:*domain* "mail.skazorama.ru")
   (setf mailgun:*api-key* "key-************************")

   (mailgun:send ("noreply@skazorama.ru"
                  "svetlyak.40wt@gmail.com"
                  "Mail subject")
     (:h1 "This is a test letter")
     (:p "It is in a HTML format and supports some tags"
         "For example, I can make " (:b "a bold text") ".")
     (:p "And here we have some items, passed to the template:")
     (:ul
      (loop for item in items
            do (mailgun:htm
                (:li item)))))

Roadmap
=======

* Add support for styles, build them with LASS and embed into an email's
  markup.

.. Everything after this comment will be omitted from HTML docs.
.. include-to

Building Documentation
======================

Provide instruction how to build or use your library.

How to build documentation
--------------------------

To build documentation, you need a Sphinx. It is
documentaion building tool written in Python.

To install it, you need a virtualenv. Read
this instructions
`how to install it
`_.

Also, you'll need a `cl-launch `_.
It is used by documentation tool to run a script which extracts
documentation strings from lisp systems.

Run these commands to build documentation::

  virtualenv --python python2.7 env
  source env/bin/activate
  pip install -r docs/requirements.txt
  invoke build_docs

These commands will create a virtual environment and
install some python libraries there. Command ``invoke build_docs``
will build documentation and upload it to the GitHub, by replacing
the content of the ``gh-pages`` branch.


Authors
=======

* Alexander Artemenko (svetlyak.40wt@gmail.com)

Copyright
=========

Copyright (c) 2018 Alexander Artemenko (svetlyak.40wt@gmail.com)


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Next: , Previous: , Up: Systems   [Contents][Index]

2.1 mailgun

Author

Alexander Artemenko

License

Unlicense

Description

A thin wrapper to post HTML emails through mailgun.com

Long Description

=========================================
mailgun - send emails from Common Lisp! =========================================

.. Everything starting from this commit will be inserted into the index page of the HTML documentation.
.. include-from

This library provides an easy way to send transactional emails through http://mailgun.com.

.. note:: You don’t have to setup your own SMTP servers!

And they have a "free" plan with 10000 emails per month.

Reasoning
=========

Previously, I used this code in one of my projects, but seems this functionality needed almost in any serious web application. So, I decided to make it available as a separate library.

Here is how to use it
=====================

First, setup an account at http://mailgun.com. You need to add your domain there and to reveive an authentication token.

.. code-block:: common-lisp

(setf mailgun:*domain* "mail.skazorama.ru")
(setf mailgun:*api-key* "key-************************")

(mailgun:send ("noreply@skazorama.ru" "svetlyak.40wt@gmail.com"
"Mail subject")
(:h1 "This is a test letter")
(:p "It is in a HTML format and supports some tags"
"For example, I can make " (:b "a bold text") ".")
(:p "And here we have some items, passed to the template:") (:ul
(loop for item in items
do (mailgun:htm
(:li item)))))

Roadmap
=======

* Add support for styles, build them with LASS and embed into an email’s markup.

.. Everything after this comment will be omitted from HTML docs.
.. include-to

Building Documentation
======================

Provide instruction how to build or use your library.

How to build documentation
————————–

To build documentation, you need a Sphinx. It is
documentaion building tool written in Python.

To install it, you need a virtualenv. Read
this instructions
‘how to install it <https://virtualenv.pypa.io/en/stable/installation/#installation>‘_.

Also, you’ll need a ‘cl-launch <http://www.cliki.net/CL-Launch>‘_. It is used by documentation tool to run a script which extracts documentation strings from lisp systems.

Run these commands to build documentation::

virtualenv –python python2.7 env
source env/bin/activate
pip install -r docs/requirements.txt
invoke build_docs

These commands will create a virtual environment and
install some python libraries there. Command “invoke build_docs“ will build documentation and upload it to the GitHub, by replacing the content of the “gh-pages“ branch.

Authors
=======

* Alexander Artemenko (svetlyak.40wt@gmail.com)

Copyright
=========

Copyright (c) 2018 Alexander Artemenko (svetlyak.40wt@gmail.com)

Version

0.2.0

Dependency

mailgun/core (system)

Source

mailgun.asd (file)


Previous: , Up: Systems   [Contents][Index]

2.2 mailgun/core

Author

Alexander Artemenko

License

Unlicense

Dependencies
Source

mailgun.asd (file)

Component

file-type.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 mailgun.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/mailgun-20210228-git/mailgun.asd

Systems

Previous: , Up: Lisp files   [Contents][Index]

3.1.2 mailgun/core/file-type.lisp

Parent

mailgun/core (system)

Location

core.lisp

Packages

mailgun/core

Exported Definitions
Internal Definitions

send-html (function)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 mailgun/core

Source

file-type.lisp (file)

Nickname

mailgun

Use List

common-lisp

Exported Definitions
Internal Definitions

send-html (function)


Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *api-key*

This can be a string or secret-values:secret-value.

Package

mailgun/core

Source

file-type.lisp (file)

Special Variable: *domain*
Package

mailgun/core

Source

file-type.lisp (file)

Special Variable: *user-agent*
Package

mailgun/core

Source

file-type.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: send (FROM EMAIL SUBJECT) &body BODY

Sends HTML letter to an email.

Body of this macro should contain a markup for spinneret library. Also, it can use "htm" macro, to wrap html markup in the inner lisp constructions such as loops and conditional expressions.

Package

mailgun/core

Source

file-type.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: send-html FROM EMAIL SUBJECT HTML-BODY
Package

mailgun/core

Source

file-type.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, mailgun.asd: The mailgun․asd file
File, Lisp, mailgun/core/file-type.lisp: The mailgun/core/file-type․lisp file

L
Lisp File, mailgun.asd: The mailgun․asd file
Lisp File, mailgun/core/file-type.lisp: The mailgun/core/file-type․lisp file

M
mailgun.asd: The mailgun․asd file
mailgun/core/file-type.lisp: The mailgun/core/file-type․lisp file

Jump to:   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   F   M   S  
Index Entry  Section

F
Function, send-html: Internal functions

M
Macro, send: Exported macros

S
send: Exported macros
send-html: Internal functions

Jump to:   F   M   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*api-key*: Exported special variables
*domain*: Exported special variables
*user-agent*: Exported special variables

S
Special Variable, *api-key*: Exported special variables
Special Variable, *domain*: Exported special variables
Special Variable, *user-agent*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   M   P   S  
Index Entry  Section

M
mailgun: The mailgun system
mailgun/core: The mailgun/core system
mailgun/core: The mailgun/core package

P
Package, mailgun/core: The mailgun/core package

S
System, mailgun: The mailgun system
System, mailgun/core: The mailgun/core system

Jump to:   M   P   S