gf78/email-validation-api

By gf78

•Updated almost 2 years ago

Restful API to validate email addresses. (Go, Alpine, desposable, allow-/denylist, MX & SMPT check)

Image

Security

API management

Web servers

2.0K

Overview Tags

gf78/email-validation-api repository overview

⁠Email Validation API (EVA)

This is a Go-based API for validating email addresses. The API includes several validation checks and security features such as rate limiting, fail2ban-like functionality, and API key authentication. The application is Dockerized for easy deployment.

⁠Example

GET /[email protected]

{ email: "[email protected]", valid: true, message: "Email [email protected] is valid", cached: false }

⁠Features

Email Format Validation: Checks if the email format is valid using a regex.
Allow/Deny Lists: Validates emails, names, or domains against allow or deny lists.
Disposal Check: Check against open source lists of disposable email services.
MX Record Check: Checks if the domain has valid MX records.
SMTP Check: Verifies the SMTP server of the domain.
Security Headers: Adds security headers to responses.
API Key Authentication: Protects the API with an API key.
Rate Limiting: Limits the number of requests a client can make.
Fail2ban-like Functionality: Temporarily bans IP addresses with too many failed login attempts.
Dockerized: Easy deployment with Docker and Docker Compose.

⁠Endpoints

⁠Validate Email Address (GET)

Method: GET
Path: [email protected]⁠ (or as query param)
Query
- email (string): The email address to validate (if not provided as path)
- nochache (boolean): If "true", bypass the cache.
- key(string): (Optional) The API key for authentication.

⁠Validate Email Address (POST)

Method: POST
Path: [email protected]⁠ (or as form data)
Form Data / Payload
- email (string): The email address to validate (if not provided as path)
- nochache (boolean): If "true", bypass the cache.
- key(string): (Optional) The API key for authentication.

⁠Checks

Check	Note
Syntax	Validate email with regex expression defined in config
Allow/Deny Lists	Validates emails, names, or domains against allow or deny lists stored in config folder
Disposal Check	List will be autogenerated/updated and stored in config folder
MX Record	Checks if the domain has valid MX records
SMTP Server	Verifies the SMTP server of the domain

⁠Installation

⁠Docker Compose

version: "3.8"

services:
  eva:
    container_name: "email-validation-api"
    image: "gf78/email-validation-api:latest"
    ports:
      - "80:80"
    environment:
      - TZ=Europe/Vienna
    volumes:
      - eva-config:/root/config
      - eva-logs:/root/logs
    healthcheck:
      test:
        [
          "CMD",
          "wget",
          "--spider",
          "--quiet",
          "--tries=1",
          "--timeout=5",
          "http://localhost:80/",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3

volumes:
  eva-config:
    external: true
    name: eva-config  

  eva-logs:
    external: true
    name: eva-logs

⁠Build

git clone https://github.com/gf78/email-validation-api.git
cd email-validation-api
chmod +x build.sh
./build.sh
docker-compose logs -f

⁠Configuration

⁠Settings

The settings are managed through a JSON file located at config/config.json.

key	default	note
regex	^[a-zA-Z0-9.!#$%&'*+/=?^_`{\|}~-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$	email syntax validaton
smtp_email	[email protected]⁠	your email, used to connect to STMP server
cache_enabled	true	Cache MX and SMTP results?
cache_max_time_mx	3600	seconds to cache MX results
cache_max_time_smtp	3600	seconds to cache SMTP results
logging_enabled	true	Write log to /logs/eva.log?
api_key	null	If set, key must be provided as query param, form data or Authorization header
requests_per_minute	60	max. number of requests per minute
fail2ban_duration	600	ban time in seconds
fail2ban_allow	[]	whitelisted ip addresses
list_name	310-deny-domain-disposable.txt"	name of auto-generated disposal domain list
list_update_interval	86400	interval of auto-generated disposal domain list generation
list_source_urls"	["https://....", "https://...."]	source domains

⁠Allow/Deny Lists

The list are stored as .txt files in the config folder. One entry per line. All lowercase.

Filename format <priority>-<action>-<content>-<(comment)>.txt

part	values	note
priority	001, 002, ... 100, 101, ... 999	priority of execution
action	allow, deny	type of list
content	name, domain, email	part of the email
comment	your_personal_note	optional

⁠Disposal Temporary Emails

The following sources of disallowed domains are preconfigured:

Tag summary

Recent tags

Content type

Image

Digest

sha256:75a714281…

Size

8.3 MB

Last updated

almost 2 years ago

docker pull gf78/email-validation-api