Welcome to {{companyName}}

Hello {{userName}}!

\n\n\nEOF\n\n# 3. Create .env file\ncat > .env << EOF\nSMTP_HOST=smtp.yourdomain.com\nSMTP_USER=your-email@domain.com\nSMTP_PASS=your-password\nFROM_EMAIL=your-email@domain.com\nFROM_NAME=Your Company\nAPI_KEYS={\"himosoft\":\"himosoft-strong-api-key\",\"admin\":\"admin-secret-key\",\"client\":\"client-api-key\"}\nEOF\n\n# 4. Start the stack\ndocker-compose up -d\n\n# 5. Copy templates to volume\ndocker run --rm -v \"$(pwd)/templates:/source\" -v hs-mail-queue_email_templates:/dest \\\n alpine cp -r /source/* /dest/\n```\n\n## 📡 API Usage\n\n### Send Email\n\n```bash\ncurl -X POST http://localhost:3000/api/send-email \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-secret-api-key\" \\\n -d '{\n \"to\": \"recipient@example.com\",\n \"subject\": \"Welcome!\",\n \"templateName\": \"welcome\",\n \"variables\": {\n \"name\": \"John Doe\",\n \"company\": \"HIMOSOFT\"\n }\n }'\n```\n\n### Health Check\n\n```bash\ncurl http://localhost:3000/api/health\n```\n\n### Queue Status\n\n```bash\ncurl -H \"X-API-Key: your-secret-api-key\" \\\n http://localhost:3000/api/queue-status\n```\n\n## 🔧 Environment Variables\n\n### Required\n\n- `SMTP_HOST` - SMTP server hostname\n- `SMTP_USER` - SMTP username/email\n- `SMTP_PASS` - SMTP password\n- `FROM_EMAIL` - Sender email address\n- `FROM_NAME` - Sender name\n- `API_KEYS` - Multiple API keys with names (JSON format)\n\n### Optional\n\n- `NODE_ENV` - Node.js environment (default: production)\n- `PORT` - API server port (default: 3000)\n- `SMTP_PORT` - SMTP server port (default: 587)\n- `SMTP_SECURE` - Use TLS/SSL (default: false)\n- `REDIS_URL` - Redis connection URL (default: redis://redis:6379)\n- `QUEUE_NAME` - BullMQ queue name (default: email-queue)\n- `MAX_RETRIES` - Maximum email retry attempts (default: 3)\n- `RETRY_DELAY` - Retry delay in milliseconds (default: 5000)\n- `FAKE_EMAIL_FILTER` - Enable disposable email filtering (default: true)\n- `ENABLE_MX_VERIFICATION` - Enable MX record verification (default: false)\n\n## 🔍 Email Validation Features\n\n### Disposable Email Detection\n\nBuilt-in protection against disposable/temporary email addresses using the FakeFilter API.\n\n**Configuration:**\n\n```env\nFAKE_EMAIL_FILTER=true # Enabled by default\n```\n\n**How it works:**\n\n- Checks email addresses against the FakeFilter API before sending\n- Blocks emails to known disposable email providers\n- Graceful degradation - allows emails if API is unavailable\n- Detailed logging in Docker logs\n\n### MX Record Verification\n\nThe worker validates that email domains have proper MX records before sending emails.\n\n**Configuration:**\n\n```env\nENABLE_MX_VERIFICATION=true # Disabled by default\n```\n\n**How it works:**\n\n- DNS lookup to check if recipient domain has MX records\n- Blocks emails to domains without valid MX records\n- Prevents sending to non-existent or misconfigured domains\n- Detailed logging showing MX record details\n\n**Example logs:**\n\n```\n🔍 MX verification: ENABLED\n🔍 Checking MX records for domain: gmail.com\n✅ MX records found for gmail.com: gmail-smtp-in.l.google.com (priority: 5), alt1.gmail-smtp-in.l.google.com (priority: 10)\n✅ MX verification: All domains have valid MX records\n```\n\n**When MX verification blocks an email:**\n\n```\n❌ Job 5 BLOCKED: No MX records for 'test@invalid-domain.xyz'\n📧 Job details: {\n jobId: '5',\n to: 'test@invalid-domain.xyz',\n subject: 'Test Email',\n blockedAddress: 'test@invalid-domain.xyz'\n}\n❌ Job 5 failed: Blocked email 'test@invalid-domain.xyz' - no MX records found\n```\n\n**Benefits:**\n\n- Reduces bounce rates\n- Improves email deliverability\n- Prevents sending to non-existent domains\n- Better sender reputation\n\n## 📝 Built-in Templates\n\nThe image includes several HTML email templates:\n\n- `welcome` - Welcome email template\n- `password-reset` - Password reset template\n- `notification` - General notification template\n\n### Using Built-in Templates\n\n```bash\ncurl -X POST http://localhost:3000/api/send-email \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-secret-api-key\" \\\n -d '{\n \"to\": \"user@example.com\",\n \"subject\": \"Password Reset\",\n \"templateName\": \"password-reset\",\n \"variables\": {\n \"resetLink\": \"https://example.com/reset?token=abc123\",\n \"expiresIn\": \"24 hours\"\n }\n }'\n```\n\n## 🎨 Custom Templates\n\n### Creating Custom Templates\n\nCreate your custom templates in a `templates` directory and mount them using Docker volumes:\n\n```yaml\nservices:\n api:\n image: himelranaswe/hs-mail-queue:latest\n volumes:\n - ./templates:/app/templates:ro # Bind mount for development\n - email_templates:/app/templates:ro # Named volume for production\n # ... other configuration\n\nvolumes:\n email_templates:\n driver: local\n```\n\n### Template Structure\n\n```\ntemplates/\n├── welcome.html\n├── order-confirmation.html\n├── newsletter.html\n└── invoice.html\n```\n\n### Simple Template Example\n\nCreate a file `templates/welcome.html`:\n\n```html\n\n\n\n \n Welcome to {{companyName}}\n \n\n\n \n \n

Hello {{userName}},

\n \n

Thank you for joining {{companyName}}! We're thrilled to have you as part of our community.

\n \n {{#if welcomeMessage}}\n

\n {{/if}}\n \n

Getting Started

{{this}}

\n \n {{#if verificationRequired}}\n

Please verify your email address to get started:

\n Verify Email\n {{/if}}\n \n {{#if dashboardUrl}}\n

Ready to explore? Visit your dashboard:

\n Go to Dashboard\n {{/if}}\n \n

If you have any questions, feel free to reach out to our support team.

\n \n

Best regards,
The {{companyName}} Team

\n \n \n\n\n```\n\n### Template Variables\n\nUse Handlebars syntax for dynamic content:\n\n| Variable Type | Syntax | Example |\n| --------------------- | ------------------------------- | ------------------------------------- |\n| **Simple** | `{{variableName}}` | `{{userName}}`, `{{companyName}}` |\n| **Conditional** | `{{#if variable}}...{{/if}}` | Show content only if variable exists |\n| **Loops** | `{{#each array}}...{{/each}}` | Iterate through arrays |\n| **Nested** | `{{object.property}}` | `{{user.firstName}}` |\n\n### Using Custom Templates\n\n```bash\ncurl -X POST http://localhost:3000/api/send-email \\\n -H \"Content-Type: application/json\" \\\n -H \"X-API-Key: your-secret-api-key\" \\\n -d '{\n \"to\": \"user@example.com\",\n \"subject\": \"Welcome to HIMOSOFT!\",\n \"templateName\": \"welcome\",\n \"variables\": {\n \"userName\": \"John Doe\",\n \"companyName\": \"HIMOSOFT\",\n \"welcomeMessage\": \"We are excited to have you join our platform!\",\n \"gettingStartedSteps\": [\n \"Complete your profile\",\n \"Explore our features\",\n \"Connect with others\"\n ],\n \"verificationRequired\": true,\n \"verificationUrl\": \"https://example.com/verify?token=abc123\",\n \"dashboardUrl\": \"https://example.com/dashboard\",\n \"currentYear\": \"2024\",\n \"contactEmail\": \"contact@himosoft.com\",\n \"supportEmail\": \"support@himosoft.com\"\n }\n }'\n```\n\n### Template Management\n\n```bash\n# List available templates\ncurl -H \"X-API-Key: your-secret-api-key\" \\\n http://localhost:3000/api/templates\n\n# Copy templates to volume (after editing)\ndocker run --rm -v \"$(pwd)/templates:/source\" -v hs-mail-queue_email_templates:/dest \\\n alpine cp -r /source/* /dest/\n\n# Restart containers to pick up changes\ndocker-compose restart api worker\n```\n\n## 🔍 Monitoring\n\n### Health Endpoints\n\n- `GET /api/health` - Basic health check\n- `GET /api/health/queue` - Queue health check\n\n### Queue Metrics\n\n- `GET /api/queue-status` - Queue statistics\n- `GET /api/templates` - Available templates\n\n## 🔒 Security\n\n- **API Key Authentication** - All endpoints require valid API key\n- **Environment Variables** - Secure credential management\n- **Network Isolation** - Redis runs in internal network\n- **Health Checks** - Built-in monitoring and validation\n\n## 📊 Performance\n\n- **Lightweight** - ~200MB optimized image\n- **Fast** - Node.js 18 Alpine base\n- **Scalable** - Multiple worker instances supported\n- **Reliable** - BullMQ with Redis persistence\n\n## 🤝 Support\n\n- 📖 [Full Documentation](https://github.com/Swe-HimelRana/hs-mail-queue)\n- 🐛 [Report Issues](https://github.com/Swe-HimelRana/hs-mail-queue/issues)\n- 💬 [Discussions](https://github.com/Swe-HimelRana/hs-mail-queue/discussions)\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/Swe-HimelRana/hs-mail-queue/blob/main/LICENSE) file for details.\n\n---\n\n**Made with ❤️ by Himel**\n","has_starred","hub_user","immutable_tags_settings",{"_71":11,"_72":73},"enabled","rules",[74],".*","is_automated","permissions",{"_78":17,"_79":11,"_80":11},"read","write","admin","user","storage_size",108345952,"orgData","recentTags",[87],{"_88":40,"_89":90,"_91":92,"_93":94,"_95":96,"_97":98,"_46":130,"_131":90,"_132":29,"_133":52,"_53":134,"_135":136,"_137":123,"_138":130,"_139":62,"_140":17},"content_type","creator",4989742,"digest","sha256:c28245bad636543b495742c30f7925f27933d3b6f3e47bd3857c47c44475b145","full_size",49518236,"id",956773660,"images",[99,114,120,126],{"_100":101,"_91":102,"_103":44,"_104":105,"_106":107,"_108":109,"_110":44,"_111":-5,"_112":94,"_59":62,"_113":-5},"architecture","amd64","sha256:3442300ad175bc77c268cac98b7daeca151545f7b8dcfd21cc5c39b42a2b332c","features","last_pulled","2026-09-07T12:14:14.410335014Z","last_pushed","2025-08-18T22:56:18.742304045Z","os","linux","os_features","os_version","size","variant",{"_100":115,"_91":116,"_103":44,"_104":117,"_106":118,"_108":109,"_110":44,"_111":-5,"_112":119,"_59":62,"_113":-5},"arm64","sha256:f612703f153cb40459c854a08803ee38b6490c3bcd1001db57e182556726cbee","2026-09-07T12:14:14.401610566Z","2025-08-18T22:56:17.409035687Z",49522963,{"_100":121,"_91":122,"_103":44,"_104":123,"_106":124,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},"unknown","sha256:56daf37365526972953285250a9d50b307aea00a33bcca15d00cc81101fae0b6","2026-09-07T12:14:14.449820989Z","2025-08-18T22:56:16.481432553Z",1231,{"_100":121,"_91":127,"_103":44,"_104":128,"_106":129,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},"sha256:c71dbb3f932c30568f8b232cfbbe1fb0f4ad14b9fe24432675b09bc0642fb896","2026-09-07T12:14:14.392666672Z","2025-08-18T22:56:20.158781039Z","2025-08-18T22:56:21.24772Z","last_updater","last_updater_username","media_type","latest","repository",28319980,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"routes/_layout.r.$namespace.$reponame.tags",{"_34":150,"_157":158,"_146":170,"_171":11},{"_36":151,"_38":152,"_41":42,"_43":44,"_45":11,"_46":47,"_48":49,"_50":153,"_53":31,"_28":29,"_54":55,"_56":40,"_57":58,"_59":60,"_61":62,"_63":-5,"_64":58,"_65":66,"_67":11,"_68":29,"_69":154,"_75":11,"_76":156,"_81":29,"_82":83},[],[40],[52],{"_71":11,"_72":155},[74],{"_78":17,"_79":11,"_80":11},"tags",{"_159":60,"_160":-5,"_161":-5,"_162":163},"count","next","previous","results",[164],{"_88":40,"_89":90,"_91":92,"_93":94,"_95":96,"_97":165,"_46":130,"_131":90,"_132":29,"_133":52,"_53":134,"_135":136,"_137":123,"_138":130,"_139":62,"_140":17},[166,167,168,169],{"_100":101,"_91":102,"_103":44,"_104":105,"_106":107,"_108":109,"_110":44,"_111":-5,"_112":94,"_59":62,"_113":-5},{"_100":115,"_91":116,"_103":44,"_104":117,"_106":118,"_108":109,"_110":44,"_111":-5,"_112":119,"_59":62,"_113":-5},{"_100":121,"_91":122,"_103":44,"_104":123,"_106":124,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},{"_100":121,"_91":127,"_103":44,"_104":128,"_106":129,"_108":121,"_110":44,"_111":-5,"_112":125,"_59":62,"_113":-5},[],"canDeleteTags","actionData","errors"]

Welcome to {{companyName}}!

Hello {{userName}}!

Welcome to {{companyName}}!

Hello {{userName}}!

Welcome to {{companyName}}!

Hello {{userName}},

Getting Started

Digest	OS/ARCH	Compressed size
3442300ad175	linux/amd64	47.22 MB
f612703f153c	linux/arm64	47.23 MB

himelranaswe/hs-mail-queue

Tags for himelranaswe/hs-mail-queue