Email Microservice

The Email microservice is a supports automated processes within the City & County of San Francisco to send templated emails via SendGrid.

Get started

First Time Setup

Databases

Install Postgres (if needed)

brew install postgresql

Create database

createdb email_microservice

Install Redis (if needed)

brew install redis

Create a local config (by copying)

cp .env.example .env

Edit the following line

export REDIS_URL=redis://localhost:6379

Start the databases

brew services start postgresql@14
brew services start redis

If you want to verify the services running, you can use

brew services list

Environment and Dependencies

Install Pipenv (if needed)

pip install --user pipenv

Install packages

pipenv install --dev

Note: if you have (mini)Conda installed, you might have to adjust the Python executable. If so, you can run something like this (see for more info):

pipenv --python=$(conda run which python) --site-packages

Migrate DB

pipenv run alembic upgrade head

Run the server

ACCESS_KEY=123456 pipenv run gunicorn --reload 'service.microservice:start_service()' --timeout 600

Start celery worker

pipenv run celery worker

API

All API endpoints must be called via HTTP POST with a JSON request body and the following headers:

ACCESS_KEY: Your API access key
Content-Type: application/json

Send an email with template

{
  "subject": "Hi Diddly Ho",
  "to": [{
    "email": "homer@springfield.com",
    "name": "Homer Simpson"
  }],
  "from": {
    "email": "ned@flandersfamily.com",
    "name": "Ned Flanders"
    "template": {
      "url": "https://static.file.com/template.html",
      "replacements" {
        "var1": "hello!",
        "var2": {
          "first_name": "homer",
          "last_name": "simpson"
        }
      }
    }
  }
}

Attachments

You can provide attachments either inline (with the base64-encoded content field) or via URL in the path field. You may also provide request headers for URL attachments that require additional authentication.

{
  "subject": "Status Report",
  "to": [{
    "email": "cburns@springfieldnuclear.com",
    "name": "Charles Burns"
  }],
  "from": {
    "email": "wsmithers@springfieldnuclear.com",
    "name": "Waylon Smithers"
  },
  "content": {
    "type": "text/plain",
    "value": "All systems are in operating condition."
  },
  "attachments": [
    {
      "content": "YmFzZTY0IHN0cmluZw==",
      "filename": "report.txt",
      "type": "text/plain"
    },
    {
      "filename": "report.pdf",
      "path": "https://www.springfieldnuclear.com/report.pdf",
      "type": "application/pdf",
      "headers": {
          "api-key": "123ABC"
      }
    }
  ]
}

Filter: clicktrack

docs.sendgrid.com

{
  "subject": "Hi Diddly Ho",
  "to": [{
    "email": "homer@springfield.com",
    "name": "Homer Simpson"
  }],
  "from": {
    "email": "ned@flandersfamily.com",
    "name": "Ned Flanders"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "Try search with https://google.com"
    }
  ],
  "filters" : {
    "clicktrack" : {
      "settings" : {
        "enable" : 0,
        "enable_text" : false
      }
    }
  }
}

Testing

Code coverage command with missing statement line numbers

pipenv run python -m pytest -s --cov=service --cov=tasks tests/ --cov-report term-missing

Revising the database

Create a migration

pipenv run alembic revision -m "Add a column"

Edit the created revision file to add the steps to implement and rollback the changes you want to make.

Run DB migrations

pipenv run alembic upgrade head

Templating

Templates are rendered with Jinja.

SFDigitalServices/email-microservice-py