{"id":31292947,"url":"https://github.com/wal33d/gmail-node-mailer","last_synced_at":"2026-02-27T03:01:09.427Z","repository":{"id":227546623,"uuid":"771229990","full_name":"Wal33D/gmail-node-mailer","owner":"Wal33D","description":"gmail-node-mailer is a Node.js library for easy email sending via the Gmail API, featuring quick setup, HTML/plain text support, and dynamic configuration for streamlined email integration.","archived":false,"fork":false,"pushed_at":"2025-06-22T05:35:21.000Z","size":899,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-09-24T17:55:18.161Z","etag":null,"topics":["email","email-sending","email-validation","gmail","gmail-api","nodejs","nodejs-library","nodemailer","npm","npm-package","opensource","package","service-account","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/gmail-node-mailer","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Wal33D.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-12T23:18:14.000Z","updated_at":"2025-06-22T05:35:25.000Z","dependencies_parsed_at":"2024-11-16T09:31:34.597Z","dependency_job_id":"9e1afc07-efa9-4abc-bd49-a305ab4ac21c","html_url":"https://github.com/Wal33D/gmail-node-mailer","commit_stats":null,"previous_names":["wal33d/gmail-node-mailer","our-node-packages/gmail-node-mailer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Wal33D/gmail-node-mailer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fgmail-node-mailer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fgmail-node-mailer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fgmail-node-mailer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fgmail-node-mailer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Wal33D","download_url":"https://codeload.github.com/Wal33D/gmail-node-mailer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Wal33D%2Fgmail-node-mailer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29883111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T23:51:21.483Z","status":"online","status_checked_at":"2026-02-27T02:00:06.759Z","response_time":57,"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":["email","email-sending","email-validation","gmail","gmail-api","nodejs","nodejs-library","nodemailer","npm","npm-package","opensource","package","service-account","typescript"],"created_at":"2025-09-24T17:48:47.311Z","updated_at":"2026-02-27T03:01:09.417Z","avatar_url":"https://github.com/Wal33D.png","language":"TypeScript","readme":"# Gmail Node Mailer\r\n\r\nSimplify your email sending process within Node.js applications with `gmail-node-mailer`. This lightweight package harnesses the power of the Gmail API to send emails effortlessly. Whether you're sending a quick notification or a detailed newsletter, `gmail-node-mailer` makes it straightforward.\r\n\r\n**GitHub Repository:** [gmail-node-mailer on GitHub](https://github.com/our-node-packages/gmail-node-mailer)\r\n\r\n**npm Package:** [gmail-node-mailer on npm](https://www.npmjs.com/package/gmail-node-mailer)\r\n\r\n## Quick Features\r\n- 🚀 Quick setup with service account credentials.\r\n- 📧 Validate and send emails with ease.\r\n- 🎨 Supports both plain text and HTML content.\r\n- 🔧 Easy configuration for service accounts and sender emails.\r\n- 📎 **New Functionality: Attachment Support** - Send attachments with your emails effortlessly.\n\n## Requirements\n\n- Node.js **14** or newer\n\n## Get Started in Seconds\n\r\n### 1. Install with NPM\r\n\r\nRun the following in your project directory:\r\n\r\n```bash\r\nnpm install gmail-node-mailer\r\n```\r\n\r\n### 2. Streamline Email Notifications with Your Server Workflow\r\n\r\n`gmail-node-mailer` is designed to seamlessly integrate into your server setup, enabling you to send emails for various events such as server start/stop notifications, error alerts, and to manage subscription events like new subscriptions or renewals.\r\n\r\n## Detailed Usage Guide\r\n### Sending Emails with Attachments\r\n\r\nWith the new attachment support, `gmail-node-mailer` allows you to include files in your emails. Here's how you can attach a PDF file to an email:\r\n\r\n```typescript\r\nimport { GmailMailer } from 'gmail-node-mailer';\r\n\r\nasync function sendEmailWithAttachment() {\r\n  const mailer = new GmailMailer();\r\n  await mailer.initializeClient({\r\n    gmailSenderEmail:'example@your-domain.com',\r\n    gmailServiceAccountPath: './path/to/your-service-account.json',\r\n  });\r\n    const attachments = [{\r\n        filename: 'Invoice.pdf',\r\n        mimeType: 'application/pdf',\r\n        content: 'base64_encoded_content_here'\r\n    }];\r\n\r\n    await mailer.sendEmail({\r\n        recipientEmail: 'customer@example.com',\r\n        subject: 'Your Invoice',\r\n        message: 'Please find attached your invoice.',\r\n        attachments: attachments\r\n    });\r\n}\r\n\r\nsendEmailWithAttachment().catch(console.error);\r\n```\r\n\r\n### Server Start/Stop Notifications\r\n\r\nSeamlessly notify about server start or stop events using `gmail-node-mailer`. Here's an example on how to set up and send these notifications:\r\n\r\n```typescript\r\nimport { GmailMailer } from 'gmail-node-mailer';\r\n\r\nasync function initializeMailer() {\r\n  const mailer = new GmailMailer();\r\n  await mailer.initializeClient({\r\n    gmailSenderEmail:'example@your-domain.com',\r\n    gmailServiceAccountPath: './path/to/your-service-account.json',\r\n  });\r\n  // Setting the initialized mailer to a global variable\r\n  global.gmailClient = mailer;\r\n}\r\n\r\nasync function notifyServerStatus(status: 'start' | 'stop') {\r\n  const message = status === 'start' ? 'Server is up and running.' : 'Server has been shut down.';\r\n  try {\r\n    await global.gmailClient.sendEmail({\r\n      recipientEmail: 'admin@example.com',\r\n      subject: `Server ${status} Notification`,\r\n      message,\r\n    });\r\n  } catch (error) {\r\n    console.error('Error sending email:', error);\r\n  }\r\n}\r\n\r\n// Initialize the GmailMailer client and then notify server status\r\ninitializeMailer().then(() =\u003e {\r\n  notifyServerStatus('start').catch(console.error);\r\n});\r\n\r\n// Further down in your server code, you can use global.gmailClient for other email sending purposes\r\n\r\n```\r\n### Use Case Examples \r\n#### New Subscription Welcome Emails\r\nWhen a new customer subscribes, sending a welcome email is a great way to start your relationship. Here's how you can set this up:\r\n\r\n```typescript\r\nimport { GmailMailer } from 'gmail-node-mailer';\r\n\r\nexport async function handleNewSubscription(customerEmail, subscriptionDetails) {\r\n    const mailer = new GmailMailer();\r\n    \r\n    await mailer.initializeClient({\r\n        gmailServiceAccountPath: './path/to/your-service-account.json',\r\n    });\r\n\r\n    const htmlMessage = `\r\n        \u003c!DOCTYPE html\u003e\r\n        \u003chtml\u003e\r\n        \u003chead\u003e\r\n            \u003cstyle\u003e\r\n                body { font-family: Arial, sans-serif; margin: 0; padding: 20px; background-color: #f0f0f0; }\r\n                .content { background-color: #fff; padding: 20px; }\r\n                h1 { color: #007bff; }\r\n            \u003c/style\u003e\r\n        \u003c/head\u003e\r\n        \u003cbody\u003e\r\n            \u003cdiv class=\"content\"\u003e\r\n                \u003ch1\u003eWelcome to Your New Adventure!\u003c/h1\u003e\r\n                \u003cp\u003eDear Adventurer, thank you for joining us. Your journey starts now!\u003c/p\u003e\r\n                \u003c!-- Add more personalized content here --\u003e\r\n            \u003c/div\u003e\r\n        \u003c/body\u003e\r\n        \u003c/html\u003e\r\n    `;\r\n\r\n    await mailer.sendEmail({\r\n        senderEmail: process.env.GMAIL_MAILER_SENDER_EMAIL,\r\n        recipientEmail: customerEmail,\r\n        subject: '🎉 Welcome to Your New Adventure!',\r\n        message: htmlMessage,\r\n    });\r\n}\r\n```\r\n\r\n#### Subscription Renewal Confirmations\r\n\r\nSimilarly, for subscription renewals, sending a confirmation email reaffirms the customer's value to your service. Here's a sample approach:\r\n\r\n```typescript\r\n// Assuming the GmailMailer is initialized similarly as in the new subscription example\r\n\r\nexport async function handleSubscriptionRenewal(customerEmail, renewalDetails) {\r\n    const htmlMessage = `\r\n        \u003c!DOCTYPE html\u003e\r\n        \u003chtml\u003e\r\n        \u003chead\u003e\r\n            \u003cstyle\u003e\r\n                body { font-family: Arial, sans-serif; margin: 0; padding: 20px; background-color: #f0f0f0; }\r\n                .content { background-color: #fff; padding: 20px; }\r\n                h1 { color: #007bff; }\r\n            \u003c/style\u003e\r\n        \u003c/head\u003e\r\n        \u003cbody\u003e\r\n            \u003cdiv class=\"content\"\u003e\r\n                \u003ch1\u003eYour Adventure Continues!\u003c/h1\u003e\r\n                \u003cp\u003eDear Adventurer, we're thrilled to have you with us for another year. Here's to more adventures together!\u003c/p\u003e\r\n                \u003c!-- Add renewal-specific content here --\u003e\r\n            \u003c/div\u003e\r\n        \u003c/body\u003e\r\n        \u003c/html\u003e\r\n    `;\r\n\r\n    // Use the initialized GmailMailer instance to send the email\r\n    await mailer.sendEmail({\r\n        senderEmail: process.env.GMAIL_MAILER_SENDER_EMAIL,\r\n        recipientEmail: customerEmail,\r\n        subject: '🎉 Thank You for Renewing Your Adventure!',\r\n        message: htmlMessage,\r\n    });\r\n}\r\n```\r\nCheck the examples directory for more samples.\r\n\r\n## Advanced Initialization and Configuration\r\n\r\n`gmail-node-mailer` offers a flexible and powerful way to initialize and configure your email sending capabilities. Here's a deep dive into customizing the initialization:\r\n\r\n### Initializing with Service Account Credentials\r\n\r\nAuthenticate using a Gmail service account for secure email sending. To do this, you need to initialize the `GmailMailer` with your service account details. \r\nThis can be done by either directly providing the service account details or specifying a file path to a JSON file containing these credentials. \r\nHere's how you can accomplish this:\r\n\r\n```typescript\r\nimport { GmailMailer } from 'gmail-node-mailer';\r\n\r\nconst mailer = new GmailMailer();\r\n\r\n// Initialize using direct service account details or a file path\r\nawait mailer.initializeClient({\r\n  gmailServiceAccount: {\r\n    client_email: 'your-service-account-email@your-project.iam.gserviceaccount.com',\r\n    private_key: '-----BEGIN PRIVATE KEY-----\\n...your-private-key...\\n-----END PRIVATE KEY-----\\n'\r\n  },\r\n  // OR\r\n  gmailServiceAccountPath: './path/to/your-service-account.json',\r\n});\r\n```\r\n\r\n### Configuring Sender Email\r\n\r\nSpecify and validate a default sender email address:\r\n\r\n```typescript\r\nimport { emailConfig } from 'gmail-node-mailer/utils/emailConfig';\nimport { validateEmailAddress } from 'gmail-node-mailer/utils/validateEmailAddress';\n\n// Set and validate the Gmail sender's email, or optionally declare the GMAIL_MAILER_SENDER_EMAIL in your .env file\nemailConfig.setGmailSenderEmail('your-email@gmail.com');\n\nconst { status, result } = validateEmailAddress({ email: 'your-email@gmail.com' });\n\nif (!status || !result) {\n    console.error('Email format is invalid. Please use a valid Gmail address.');\n} else {\n    console.log('Sender email configured successfully.');\n}\n\r\n```\r\n### example sendEmail function response --\u003e \r\n```typescript\r\n{\r\n  sendMailResult: {\r\n    sent: true,\r\n    status: 200,\r\n    statusText: 'OK',\r\n    responseUrl: 'https://gmail.googleapis.com/gmail/v1/users/me/messages/send',\r\n    message: 'Email successfully sent to waleed@glitchgaming.us.',\r\n    gmailResponse: {\r\n      config: [Object],\r\n      data: [Object],\r\n      headers: [Object],\r\n      status: 200,\r\n      statusText: 'OK',\r\n      request: [Object]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n\r\n### HTML or Plain Text Auto-Detection\r\nAutomatically encodes the subject line ensuring compatibility across all email clients.\r\nWrite your message in either format, and `gmail-node-mailer` will handle the rest, ensuring it's correctly formatted.\r\nTo enhance clarity and consistency in the readme section for environment configuration, consider the revised version below:\r\n\r\n---\r\n\r\n## Environment Configuration for `gmail-node-mailer`\r\n\r\nTo ensure smooth integration of `gmail-node-mailer` into your Node.js project, it's crucial to configure the environment variables detailed below. These variables can be set directly in your environment or passed during the instantiation of `gmail-node-mailer`.\r\n\r\n### Optional Environment Variables for Service Account Configuration\r\n\r\nConfigure the following optional environment variables for detailed control over service account usage:\r\n\r\n- **`GMAIL_MAILER_SENDER_EMAIL`**: Defines the email address from which emails will be sent.\r\n\r\n- **`GMAIL_MAILER_SERVICE_ACCOUNT`**: In scenarios such as production environments or instances where direct file access is not feasible, this variable allows you to input your service account credentials as a JSON string within an environment variable. \r\n\r\n  Example usage:\r\n  ```plaintext\r\n  GMAIL_MAILER_SERVICE_ACCOUNT={\"type\":\"service_account\",\"project_id\":\"...\",\"private_key_id\":\"...\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\\\n...\\\\n-----END PRIVATE KEY-----\\\\n\",\"client_email\":\"....iam.gserviceaccount.com\",\"client_id\":\"...\",\"auth_uri\":\"...\",\"token_uri\":\"...\",\"auth_provider_x509_cert_url\":\"...\",\"client_x509_cert_url\":\"...\"}\r\n  ```\r\n  **Note**: Ensure that special characters within the JSON (e.g., newlines in the private key) are properly escaped. While this example aims for readability, real-world usage might require meticulous JSON formatting or escaping.\r\n\r\n- **`GMAIL_MAILER_SERVICE_ACCOUNT_PATH`**: Primarily for development environments, this variable designates the path to the local JSON file containing your service account credentials. \r\n\r\n  Example usage:\r\n  ```plaintext\r\n  GMAIL_MAILER_SERVICE_ACCOUNT_PATH=./private/somnus_gmail_service_account.json\r\n  ```\r\n  **Note**: Verify that the specified path is accurate, relative to your project's root directory.\n\n### Sample `.env`\n\n```env\nGMAIL_MAILER_SENDER_EMAIL=sender@example.com\n# Path to your local service account JSON\nGMAIL_MAILER_SERVICE_ACCOUNT_PATH=./path/to/service-account.json\n# Or provide the service account JSON directly\n# GMAIL_MAILER_SERVICE_ACCOUNT={\"type\":\"service_account\",...}\n```\n\r\n## Additional Information and Examples\r\n\r\nFor more detailed information on configuring `gmail-node-mailer`, including setting up environment variables, sample code, please refer to the following documents in the `/info` directory:\r\n\r\n- [Environment Variables Setup](https://github.com/our-node-packages/gmail-node-mailer/blob/master/info/environment_variables.md): A guide on setting up and using the `GMAIL_MAILER_SERVICE_ACCOUNT_PATH` and `GMAIL_MAILER_SERVICE_ACCOUNT` variables for development and production environments.\r\n\r\n- [Handling New Subscriptions Example](https://github.com/our-node-packages/gmail-node-mailer/blob/master/info/handling-new-subscriptions-example.md): An example script showing how to integrate `gmail-node-mailer` for handling new subscription notifications.\r\n\r\n- [sendEmail Function Types](https://github.com/our-node-packages/gmail-node-mailer/blob/master/info/sendEmail_function_types.md): Documentation on the `sendEmail` function, including parameters and expected results.\r\n\r\n- [Server Notifications Example](https://github.com/our-node-packages/gmail-node-mailer/blob/master/info/server-notifications-example.md): A detailed example on setting up server start/stop notifications using `gmail-node-mailer`.\r\n\r\n- [Service Account Setup](https://github.com/our-node-packages/gmail-node-mailer/blob/master/info/service_account_setup.md): Step-by-step instructions on setting up a Gmail service account for use with `gmail-node-mailer`.\n\n## License\n\nThis project is licensed under the [GNU Lesser General Public License v3.0](LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwal33d%2Fgmail-node-mailer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwal33d%2Fgmail-node-mailer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwal33d%2Fgmail-node-mailer/lists"}