{"id":18537823,"url":"https://github.com/supersaashq/useemail","last_synced_at":"2025-04-05T11:06:42.478Z","repository":{"id":259203505,"uuid":"876687237","full_name":"SupersaasHQ/useEmail","owner":"SupersaasHQ","description":"A unified library to send emails - Choose your own email provider","archived":false,"fork":false,"pushed_at":"2025-03-17T05:11:55.000Z","size":166,"stargazers_count":83,"open_issues_count":1,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-29T10:05:50.940Z","etag":null,"topics":["javascript","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/use-email","language":"TypeScript","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/SupersaasHQ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-10-22T11:51:25.000Z","updated_at":"2025-03-25T05:06:35.000Z","dependencies_parsed_at":"2024-11-06T19:42:28.499Z","dependency_job_id":"4aa2dc61-04bc-4b99-a059-98a554933d58","html_url":"https://github.com/SupersaasHQ/useEmail","commit_stats":{"total_commits":15,"total_committers":3,"mean_commits":5.0,"dds":0.4,"last_synced_commit":"0248441a3582d67a41baab54d779301980b102b3"},"previous_names":["supersaashq/useemail"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SupersaasHQ%2FuseEmail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SupersaasHQ%2FuseEmail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SupersaasHQ%2FuseEmail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SupersaasHQ%2FuseEmail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SupersaasHQ","download_url":"https://codeload.github.com/SupersaasHQ/useEmail/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"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":["javascript","typescript"],"created_at":"2024-11-06T19:40:30.150Z","updated_at":"2025-04-05T11:06:42.445Z","avatar_url":"https://github.com/SupersaasHQ.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Supersaas/UseEmail\n\n\u003c!-- automd:badges color=yellow --\u003e\n\n[![npm version](https://img.shields.io/npm/v/use-email?color=yellow)](https://npmjs.com/package/use-email)\n[![npm downloads](https://img.shields.io/npm/dm/use-email?color=yellow)](https://npmjs.com/package/use-email)\n\n\u003c!-- /automd --\u003e\n\nA unified TypeScript hook for sending emails across multiple providers with a single interface. This package simplifies email sending operations by providing a consistent API regardless of the underlying email service provider.\n\n## Features\n\nUnified interface for multiple email providers\nTypeScript support for enhanced developer experience\nWorks with Node.js, Bun, Deno, and Cloudflare Workers\nEasy to switch between providers without changing your code\nSupports modern email providers\n\n## Supported Providers\n\n1. Resend\n2. SendGrid\n3. Postmark\n4. Plunk\n5. Mailgun\n6. Zeptomail (Zoho)\n\nInstallation\nYou can install the package using your preferred package manager:\n\n## Before calling any provider\n\nUpdate the .env file with the provider that you wil support:\n\n```env\n# Mailgun\nMAILGUN_API_KEY=\u003cTOKEN\u003e\nMAILGUN_DOMAIN=\u003cDOMAIN\u003e\n\n#Plunk\nPLUNK_API_TOKEN=\u003cTOKEN\u003e\n\n#Postmark\nPOSTMARK_SERVER_TOKEN=\u003ctoken\u003e\n\n#Resend\nRESEND_API_TOKEN=\u003cTOKEN\u003e\n\n#Sendgrid\nSENDGRID_API_KEY=\u003cTOKEN\u003e\n\n#ZEPTOMAIL\nZEPTOMAIL_API_KEY=\u003cTOKEN\u003e\n```\n\n## Usage\n\n```ts\nimport { useEmail } from \"use-email\";\n\nconst emailService = useEmail(\"resend\"); // Choose your provider\n\nawait emailService.send({\n  from: \"sender@example.com\",\n  to: \"recipient@example.com\",\n  subject: \"Hello from use-email!\",\n  text: \"This is a test email sent using use-email package.\",\n});\n```\n\n## Switching Providers\n\n```ts\nconst resendService = useEmail(\"resend\");\nconst sendgridService = useEmail(\"sendgrid\");\nconst postmarkService = useEmail(\"postmark\");\nconst plunkService = useEmail(\"plunk\");\nconst mailgunService = useEmail(\"mailgun\");\nconst zeptomailService = useEmail(\"zeptomail\");\n```\n\n## Email Options\n\nThe send method accepts an EmailOptions object with the following properties:\n\n```ts\ntype EmailOptions = {\n  from: string; // Sender email address\n  to: string | string[]; // Recipient email address(es)\n  subject: string; // Email subject\n  html?: string; // HTML content of the email (optional)\n  text?: string; // Plain text content of the email (optional)\n};\n```\n\n## Error Handling\n\nThe package throws errors for common issues such as missing API keys or required email fields. Always wrap your email sending code in a try-catch block:\n\n```ts\ntry {\n  await emailService.send({\n    from: \"sender@example.com\",\n    to: \"recipient@example.com\",\n    subject: \"Test Email\",\n    text: \"This is a test.\",\n  });\n  console.log(\"Email sent successfully\");\n} catch (error) {\n  console.error(\"Failed to send email:\", error);\n}\n```\n\n## TypeScript Support\n\nThis package is written in TypeScript and provides type definitions out of the box. You'll get full IntelliSense and type checking when using it in a TypeScript project.\n\n## Installation\n\nYou can install the package using your preferred package manager:\n\n\u003c!-- automd:pm-install --\u003e\n\n```sh\n# ✨ Auto-detect\nnpx nypm install use-email\n\n# npm\nnpm install use-email\n\n# yarn\nyarn add use-email\n\n# pnpm\npnpm install use-email\n\n# bun\nbun install use-email\n```\n\n\u003c!-- /automd --\u003e\n\nImport:\n\n**ESM** (Node.js, Bun)\n\n```js\nimport { useEmail } from \"use-email\";\n```\n\n**CommonJS** (Legacy Node.js)\n\n```js\nconst { useEmail } = require(\"use-email\");\n```\n\n**CDN** (Deno, Bun and Browsers)\n\n```js\nimport { useEmail } from \"https://esm.sh/use-email\";\n```\n\n## API Reference\n\n### `useEmail(provider: EmailProvider)`\n\nCreates an email service instance for the specified provider.\n\n**Parameters:**\n\n- `provider`: One of `\"resend\"` | `\"sendgrid\"` | `\"postmark\"` | `\"plunk\"` | `\"mailgun\"` | `\"zeptomail\"`\n\n**Returns:**\n\n- An email service instance with a `send` method\n\n### `send(options: EmailOptions)`\n\nSends an email using the configured provider.\n\n**Parameters:**\n\n- `options`: EmailOptions object with the following properties:\n  ```ts\n  type EmailOptions = {\n    from: string; // Sender email address\n    to: string | string[]; // Recipient email address(es)\n    subject: string; // Email subject\n    html?: string; // HTML content of the email (optional)\n    text?: string; // Plain text content of the email (optional)\n  };\n  ```\n\n**Returns:**\n\n- A Promise that resolves when the email is sent successfully\n\n**Example:**\n\n```ts\nconst emailService = useEmail(\"resend\");\n\ntry {\n  await emailService.send({\n    from: \"noreply@yourdomain.com\",\n    to: [\"user@example.com\", \"another@example.com\"],\n    subject: \"Welcome!\",\n    html: \"\u003ch1\u003eWelcome to our service!\u003c/h1\u003e\",\n    text: \"Welcome to our service!\",\n  });\n} catch (error) {\n  console.error(\"Failed to send email:\", error);\n}\n```\n\n## Development\n\n\u003cdetails\u003e\n\n\u003csummary\u003elocal development\u003c/summary\u003e\n\n- Clone this repository\n- Install latest LTS version of [Node.js](https://nodejs.org/en/)\n- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`\n- Install dependencies using `pnpm install`\n- Run interactive tests using `pnpm dev`\n\n\u003c/details\u003e\n\n## License\n\nPublished under the [MIT](https://github.com/SupersaasHQ/useEmail/blob/main/LICENSE) license.\nMade by [community](https://github.com/SupersaasHQ/useEmail/graphs/contributors) 💛\n\u003cbr\u003e\u003cbr\u003e\n\u003ca href=\"https://github.com/SupersaasHQ/useEmail/graphs/contributors\"\u003e\n\u003cimg src=\"https://contrib.rocks/image?repo=SupersaasHQ/useEmail\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupersaashq%2Fuseemail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupersaashq%2Fuseemail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupersaashq%2Fuseemail/lists"}