Skip to content

Latest commit

 

History

History
106 lines (81 loc) · 3.5 KB

README.md

File metadata and controls

106 lines (81 loc) · 3.5 KB
Raw

Node Email API

The API is built on top of Node.js with Express.js, Nodemailer and Handlebars.

Sending emails can be a challenge at times, especially consistent, responsive and well designed HTML emails with all the css goodness.

Feature list

  • Single POST endpoint for emails
  • Secured with API Keys (must serve over HTTPS in production)
  • No database required (can be added if required)
  • Configurations for
    • Transports (Create transports for Gmail, SendGrid and Office365)
    • Profiles (One or more transport definitions)

Transport Configurations

SendGrid

  • You will need a SendGrid API Key, you can be generated once you have an account.

Gmail

Office 365

  • You must have an Office 365 account with an active Office 365 E3 license and have Authenticed SMTP access.
  • If your account has 2FA enabled, you must also create an App Password to be used in the API.
  • https://mysignins.microsoft.com/security-info

Getting Started

Download or clone the project, then run npm install to install required dependencies.

Create a .env file in the root for app secrets. See .env-example, copy content into the new file and set the credentials for the transport you are using.

Use an API client like Postman to add the following.

  • Method: POST
  • URL: http://localhost:3000/email
  • Header: x-api-key (and value).
  • Body: (below)
  • Set profileName to match transport.
// development01 = gmail
// development02 = office365
// development03 = sendgrid
{
    "profileName": "development01",
    "message": {
        "to": [
            "your@email.address"
        ],
        "subject": "🥳 Node Email Service",
        "template": "example-1", // must match template naming
        "context": {
            "name": "Your Name"
        }
    }
}

Further Configuration

Profiles

src/config/profiles.config.js

This file allows you to create a profiles for a given transport. Each profile also has a from address object as required by most service providers.

// Example using the Gmail transport for profile 'development01'
case 'development01':
    return {
        transporter: transport.createGmail(env.email.gmail.email, env.email.gmail.password),
        address: {
            to: ['...'], // This will overwrite the [to] prop from request body [message.to]
            from: {
                name: 'Gmail Node Email API',
                address: env.email.gmail.email
            }
        }
    }
    // More profiles in the switch statement

Templates

Templates require 2 files, a view (.handlebars) and context (.js) file. These must be in the following folders with the same file name.

  • /src/templates/context/example-1.js
    • The context file must exist.
    • It must export an object with optional default values. (can be empty module.export = {})
    • This file will be merged with the layout.js file and request body.
  • /src/templates/view/example-1.handlebars
    • This file contains the HTML within the layout.handlebars file.

Analyse the files to understand how to embed images and data.

The message configuration is combination of