Escargo: The Zero-Configuration Email API

Written by

Don’t Re-Invent the Wheel


One of the principles of REST APIs is the ability to reuse common parts, starting from the ground up. Then, if one of those parts is broken, just go in, fix that part, and you’re good to go.

Which is why I was a bit baffled recently when I was starting on a project and looked for some plug-and-play method for creating users. After all, in today’s social-driven world, any kind of content management system is bound to have a basic username/password (or, better yet, email/password) foundation.

However, my search came up empty.

NOTE: Yeah, I realize “escargo” should be “escargot.” Later on I may change it.

Starting Small


So I decided to start my own project called Refactor, which is a set of projects with common functionalities (in the form of microservices) to build a CMS from the ground up.

I started with a user system (which is coming soon), but then realized that part of a user management system was email. There are various situations in which a CMS needs to email a user:

  • Verification of new user accounts.
  • Password reset/reminder (preferably a reset since the database is not supposed to know a password).
  • Marketing, advertising, notifications, etc.

Obviously, as ubiquitous as email is these days most languages have some semblance of an email library. But the fact that libraries exist to do this only constitutes automated emails from scratch with the framework. This breaks a tenant of REST API methodology.

Introducing: Escargo[t]


Hence, I created Escargo, the zero-configuration REST API for email. Literally all one needs on his system is Vagrant (and git, for now) and he’ll be able to get a REST API up and running for email.

The power here is that there’s absolutely no configuration and no setup. The microservice is up instantly and the user can send an email easily.

Wait? No configuration?

That’s right. Well, almost right. The configuration needs to be passed in to the POST body. For example:

    "connection": {
        "conn_type": "smtp",
        "host": "",
        "port": 587
    "options": {
        "debug_level": 2,
        "login": {
            "user": "",
            "password": "super-secret-pa55word"
        "starttls": {}
    "sending": {
        "from": "",
        "to": "",
        "subject": "Hello from Escargo!",
        "message": {
            "text_body": "This is a test of Escargo, the 0-config Email API"

I essentially just translated Python’s smtplib to a function that was ready for a JSON structure. There’s only one endpoint to the service (POST /), that takes a body describing the type of connection, any options associated with the email, and anything you want to send with the email (HTML data, images, etc.)

Documentation on the project can be read on the project’s GitHub Page

This Isn’t The End

This is only the base of the pyramid. I’ll be coming up with more microservices to add to the Refraction project.

And if you have an open source project you think should be added, email me and I’ll be sure to add it.

Did you like this article?

Did you know I'm available for hire?

Send me an email here:

Or connect with me in Wire: @nswered