{"id":27398281,"url":"https://github.com/gni/api-smtp","last_synced_at":"2025-10-20T07:41:47.254Z","repository":{"id":249547949,"uuid":"831531134","full_name":"gni/api-smtp","owner":"gni","description":"A proof-of-concept FastAPI-based service for sending emails via SMTP. Supports plain text and HTML emails, with or without attachments. Includes validation, error handling and Swagger UI documentation. Ideal for educational purposes and demonstrations.","archived":false,"fork":false,"pushed_at":"2024-12-09T22:41:13.000Z","size":18,"stargazers_count":43,"open_issues_count":0,"forks_count":2,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-27T15:47:32.512Z","etag":null,"topics":["api","api-rest","fastapi","minio","nginx","smtp","smtp-mail"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gni.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-20T20:44:36.000Z","updated_at":"2025-02-14T13:16:07.000Z","dependencies_parsed_at":"2024-11-25T09:06:44.206Z","dependency_job_id":"08f74996-340d-492d-a4be-1ef038636270","html_url":"https://github.com/gni/api-smtp","commit_stats":null,"previous_names":["exaluc/api-smtp","ioluc/api-smtp","gni/api-smtp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gni%2Fapi-smtp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gni%2Fapi-smtp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gni%2Fapi-smtp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gni%2Fapi-smtp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gni","download_url":"https://codeload.github.com/gni/api-smtp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248807270,"owners_count":21164653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","fastapi","minio","nginx","smtp","smtp-mail"],"created_at":"2025-04-14T01:30:32.278Z","updated_at":"2025-10-20T07:41:47.140Z","avatar_url":"https://github.com/gni.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SMTP Email Sending API\n\nThis project is a proof of concept API for sending emails via SMTP, built using FastAPI. It supports both sending emails with and without attachments. The project leverages MinIO for object storage and includes configurations for SMTP settings and API key validation.\n\n## Features\n\n- Send emails via SMTP.\n- Support for sending emails with attachments.\n- Validation for email fields including recipient email, subject, body, and attachments.\n- Uses MinIO for storing attachments.\n- Includes API key authentication for secure access.\n\n## Project Structure\n\n```\n.\n├── docker-compose.yml\n├── readme.md\n└── src\n    ├── app\n    │   ├── main.py\n    │   ├── requirements.txt\n    │   └── smtp_config.json\n    ├── docker\n    │   └── Dockerfile\n    └── nginx\n        ├── conf.d\n        │   └── default.conf\n        └── nginx.conf\n\n5 directories, 8 files\n```\n\n## Configuration\n\nThe SMTP settings and API key are stored in the `smtp_config.json` file. The structure of this file should be as follows:\n\n```json\n{\n    \"api_key\": \"your_api_key\",\n    \"api_name\": \"High-Performance SMTP API\",\n    \"api_description\": \"SMTP API mail dispatch with support for attachments.\",\n    \"smtp_server\": \"maildev\",\n    \"smtp_port\": 1025,\n    \"max_len_recipient_email\": 64,\n    \"max_len_subject\": 255,\n    \"max_len_body\": 50000,\n    \"use_ssl\": false,\n    \"use_password\": false,\n    \"use_tls\": false,\n    \"sender_email\": \"your_email@example.com\",\n    \"sender_domain\": \"devel.local.email\",\n    \"sender_password\": \"your_password\",\n    \"minio_server\": \"minio:9000\",\n    \"minio_access_key\": \"minioadmin\",\n    \"minio_secret_key\": \"minioadmin\",\n    \"minio_secure\": false\n}\n```\n\n## Installation\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/gni/api-smtp.git\ncd api-smtp\n```\n\n2. Set up and run Docker containers for MinIO and other dependencies:\n\n```bash\ndocker-compose up\n```\n\n## Usage\n\n### Sending Email with Attachments\n\nEndpoint: `/v1/mail/send-with-attachments`\nMethod: `POST`\nContent-Type: `multipart/form-data`\n\n#### cURL Example\n\n```bash\ncurl -X 'POST' \\\n  'http://localhost/v1/mail/send-with-attachments' \\\n  -H 'accept: application/json' \\\n  -H 'X-API-Key: your_api_key' \\\n  -H 'Content-Type: multipart/form-data' \\\n  -F 'recipient_email=string@dev.local' \\\n  -F 'subject=Sending mp4 file' \\\n  -F 'body=\u003ch1\u003eFile MP4\u003c/h1\u003e' \\\n  -F 'body_type=html' \\\n  -F 'debug=false' \\\n  -F 'attachments=@file.mp4'\n```\n\n### Sending Email without Attachments\n\nEndpoint: `/v1/mail/send`\nMethod: `POST`\nContent-Type: `application/json`\n\n#### cURL Example\n\n```bash\ncurl -X 'POST' \\\n  'http://localhost/v1/mail/send' \\\n  -H 'accept: application/json' \\\n  -H 'X-API-Key: your_api_key' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n  \"recipient_email\": \"string@dev.local\",\n  \"subject\": \"Sending json\",\n  \"body\": \"Email sended trough api\",\n  \"body_type\": \"plain\",\n  \"debug\": false\n}'\n```\n\n## API Documentation\n\nAPI documentation is available at:\n\n- Swagger UI: [http://localhost/docs](http://localhost/docs)\n- ReDoc: [http://localhost/redoc](http://localhost/redoc)\n\n## Error Handling\n\nThe API handles various SMTP errors and logs the results in JSON files stored under the `data` directory, categorized by date and status (success or failure).\n\n## Contribution\n\nFeel free to open issues or submit pull requests with improvements. Contributions are welcome!\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Author\n\n- [Lucian BLETAN](https://github.com/gni)\n\n\u003c!-- DOCKUMENTOR START --\u003e\n\n### 🐳 Service: nginx\n- **Image**: nginx:latest\n- **Ports**: 127.0.0.1:80:80\n- **Volumes**: ./src/nginx/nginx.conf:/etc/nginx/nginx.conf:ro, ./src/nginx/conf.d:/etc/nginx/conf.d:ro\n- **Depends On**: api-smtp\n- **Command**: No command specified\n#### Environment Variables\n\n| Variable | Value |\n|----------|-------|\n\n### 🐳 Service: api-smtp\n- **Image**: \n- **Ports**: internal:8000:8000\n- **Volumes**: ./data:/app/data\n- **Depends On**: \n- **Command**: No command specified\n#### Environment Variables\n\n| Variable | Value |\n|----------|-------|\n| MODULE_NAME | main |\n| VARIABLE_NAME | app |\n\n### 🐳 Service: maildev\n- **Image**: maildev/maildev\n- **Ports**: 127.0.0.1:1080:1080, 127.0.0.1:1025:1025\n- **Volumes**: \n- **Depends On**: \n- **Command**: No command specified\n#### Environment Variables\n\n| Variable | Value |\n|----------|-------|\n| MAILDEV_SMTP_PORT | 1025 |\n| MAILDEV_WEB_PORT | 1080 |\n\n### 🐳 Service: minio\n- **Image**: minio/minio\n- **Ports**: 127.0.0.1:9000:9000, 127.0.0.1:9001:9001\n- **Volumes**: \n- **Depends On**: \n- **Command**: server /data --console-address \":9001\"\n#### Environment Variables\n\n| Variable | Value |\n|----------|-------|\n| MINIO_ROOT_USER | minioadmin |\n| MINIO_ROOT_PASSWORD | minioadmin |\n\n### 🐳 Service: minio-client\n- **Image**: minio/mc\n- **Ports**: \n- **Volumes**: \n- **Depends On**: minio\n- **Command**: No command specified\n#### Environment Variables\n\n| Variable | Value |\n|----------|-------|\n\n\n\n## Networks\n\n\n\n## Graphs\n\n### Network depend\n```mermaid\nflowchart TD\nnginx[\"nginx\u003cbr\u003enginx:latest\u003cbr\u003ePorts: 127.0.0.1:80:80\"]\napi_smtp --\u003e nginx\napi_smtp[\"api-smtp\u003cbr\u003e\u003cbr\u003ePorts: internal:8000:8000\"]\nmaildev[\"maildev\u003cbr\u003emaildev/maildev\u003cbr\u003ePorts: 127.0.0.1:1080:1080, 127.0.0.1:1025:1025\"]\nminio[\"minio\u003cbr\u003eminio/minio\u003cbr\u003ePorts: 127.0.0.1:9000:9000, 127.0.0.1:9001:9001\"]\nminio_client[\"minio-client\u003cbr\u003eminio/mc\"]\nminio --\u003e minio_client\n\n```\n\n### Services depend\n```mermaid\nsankey-beta\napi_smtp, nginx, 1\nminio, minio_client, 1\n```\n\n### Services ports\n```mermaid\nsankey-beta\nExternal, maildev, 1\nExternal, minio, 1\nExternal, nginx, 1\nInternal, api_smtp, 1\nNo Network, minio_client, 1\n```\n\n## Service Interaction Sequence Diagram\n\n```mermaid\nsequenceDiagram\n    participant nginx as nginx\u003cbr\u003enginx:latest\n    participant api_smtp as api-smtp\u003cbr\u003e\n    participant maildev as maildev\u003cbr\u003emaildev/maildev\n    participant minio as minio\u003cbr\u003eminio/minio\n    participant minio_client as minio-client\u003cbr\u003eminio/mc\n    api_smtp-\u003e\u003enginx: request/response\n    minio-\u003e\u003eminio_client: request/response\n\n```\n\n## Example Commands\n\n- **Start Services**: `docker compose up -d`\n- **Stop Services**: `docker compose down`\n- **View Logs for a Service**: `docker compose logs [service]`\n\n## Troubleshooting\n\n\n- Ensure Docker is running before starting services.\n\n- Check container logs if a service fails to start.\n\n- Verify network connections if services can't communicate.\n\n\n## Maintenance Tips\n\n\n- To update a service, modify the image tag and run `docker-compose up -d`.\n\n- Review and apply environment variable changes without rebuilding containers.\n\n\u003c!-- DOCKUMENTOR END --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgni%2Fapi-smtp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgni%2Fapi-smtp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgni%2Fapi-smtp/lists"}