{"id":18867944,"url":"https://github.com/hodfords-solutions/nestjs-mailer","last_synced_at":"2025-10-10T15:07:38.082Z","repository":{"id":257806025,"uuid":"560869215","full_name":"hodfords-solutions/nestjs-mailer","owner":"hodfords-solutions","description":"Simplifies sending emails in NestJS apps","archived":false,"fork":false,"pushed_at":"2025-04-15T05:19:56.000Z","size":340,"stargazers_count":42,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-11T22:36:32.548Z","etag":null,"topics":["mailer","nestjs","nodejs"],"latest_commit_sha":null,"homepage":"https://opensource.hodfords.uk/nestjs-mailer","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hodfords-solutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2022-11-02T12:59:13.000Z","updated_at":"2025-07-04T13:31:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"0cf69ea5-0c01-4f67-9028-34e7e27dd968","html_url":"https://github.com/hodfords-solutions/nestjs-mailer","commit_stats":null,"previous_names":["hodfords-solutions/nestjs-mailer"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/hodfords-solutions/nestjs-mailer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-mailer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-mailer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-mailer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-mailer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hodfords-solutions","download_url":"https://codeload.github.com/hodfords-solutions/nestjs-mailer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hodfords-solutions%2Fnestjs-mailer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279004563,"owners_count":26083734,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["mailer","nestjs","nodejs"],"created_at":"2024-11-08T05:11:56.316Z","updated_at":"2025-10-10T15:07:38.067Z","avatar_url":"https://github.com/hodfords-solutions.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"http://opensource.hodfords.uk\" target=\"blank\"\u003e\u003cimg src=\"https://opensource.hodfords.uk/img/logo.svg\" width=\"320\" alt=\"Hodfords Logo\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e \u003cb\u003enestjs-mailer\u003c/b\u003e simplifies integrating and managing email functionalities in NestJS applications, making email operations easier and more efficient.\u003c/p\u003e\n\n## Installation 🤖\n\nInstall the `nestjs-mailer` package with:\n\n```\nnpm install @hodfords/nestjs-mailer --save\n```\n\nTo configure the mailer module dynamically, use `forRoot` to define your email template renderers, transport settings, and default sender email.\n\n```typescript\nexport const mailConfig = MailerModule.forRoot({\n    renders: {\n        adapters: [\n            new HbsAdapter({\n                templateFolder: path.join(env.ROOT_PATH, `mails/templates/${getEmailFolder()}`),\n                defaultVariable: async () =\u003e getMailConfigurations()\n            }),\n            new TranslateAdapter((text: string, options: any) =\u003e trans(text, options)),\n            new MjmlAdapter()\n        ],\n\t\ttransport: env.MAILER_URL,\n        defaultFrom: env.CONTACT_MAIL_ADDRESS\n    },\n    ...\n});\n```\n\nFor more advanced use cases where additional services or repositories are required, you can register the module using `forRootAsync`. This allows injecting services, repositories, or even database connections for more complex setups\n\n```typescript\nexport const mailConfig = MailerModule.forRootAsync({\n    imports: [CoreModule],\n    inject: [Connection, StorageService],\n    useFactory: (connection: Connection, storageService: StorageService) =\u003e {\n        const settingRepo = connection.getCustomRepository(SettingRepository);\n        const hbsAdapter = new HbsAdapter({\n            templateFolder: path.join(env.ROOT_PATH, `mails/templates/${getEmailFolder()}`),\n            defaultVariable: async (mail: BaseMail) =\u003e {\n                const variables = getMailConfigurations();\n                if (mail.isWhitelabeled) {\n                    const setting = await settingRepo.findOne({ tenant: mail.tenantId });\n                    variables.logoUrl = await storageService.generateBlobUrl(setting.blobLogo);\n                }\n                return variables;\n            }\n        });\n        return {\n            renders: {\n                adapters: [\n                    hbsAdapter,\n                    new TranslateAdapter((text: string, options: any) =\u003e trans(text, options)),\n                    new MjmlAdapter()\n                ]\n            },\n            transport: env.MAILER_URL,\n            defaultFrom: env.CONTACT_MAIL_ADDRESS\n        };\n    }\n});\n```\n\n## Usage 🚀\n\n### Adapters\n\nCurrently, nestjs-mailer supports the following adapters:\n\n-   `HbsAdapter`: For rendering Handlebars templates with dynamic variables and templates.\n-   `TranslateAdapter`: For handling multi-language support and translations.\n-   `MjmlAdapter`: For generating responsive HTML emails using MJML templates.\n\n### Defining an Email\n\nTo define a custom email, extend the BaseMail class and specify the email subject, template path, and data.\n\nHere's an example of how to define a `WelcomeEmail`:\n\n```typescript\nimport { BaseMail } from '@hodfords/nestjs-mailer';\n\nexport class WelcomeMail extends BaseMail {\n    constructor(private email: string) {\n        super();\n    }\n\n    get subject(): string {\n        return 'Welcome to Hodfords!';\n    }\n\n    get template(): string {\n        return path.join(env.ROOT_PATH, 'welcome-mail.mail.hbs');\n    }\n\n    data(): Record\u003cstring, any\u003e {\n        return {\n            content:\n                \"Welcome to our system! We're excited to have you on board and look forward to providing you with a seamless and enjoyable experience.\"\n        };\n    }\n\n    get to(): string {\n        return this.email;\n    }\n}\n```\n\n### Sending an Email\n\nTo send an email, inject the `MailerService` into your service and utilize the appropriate method for sending emails\n\n```typescript\nimport { MailService } from '@hodfords/nestjs-mailer';\n\n@Injectable()\nclass YourService {\n    constructor(private mailService: MailerService) {}\n}\n```\n\nYou have two options for sending emails:\n\n-   **Send Immediately**: Send a single email right away.\n\n```typescript\n1. const mail = new WelcomeMail(user.email);\nawait this.mailService.send(mail);\n```\n\n-   **Add to Queue**: Use this method when you need to send a large number of emails. Emails will be queued and sent\n    asynchronously.\n\n```typescript\nfor (const user of users) {\n    const mail = new WelcomeMail(user.email);\n    await this.mailService.addToQueue(mail);\n}\n```\n\n## License 📝\n\nThis project is licensed under the MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhodfords-solutions%2Fnestjs-mailer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhodfords-solutions%2Fnestjs-mailer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhodfords-solutions%2Fnestjs-mailer/lists"}