{"id":16222086,"url":"https://github.com/hugodf/buttondown","last_synced_at":"2025-09-08T14:38:08.477Z","repository":{"id":37852337,"uuid":"254705038","full_name":"HugoDF/buttondown","owner":"HugoDF","description":"Node.js/TypeScript Buttondown API client","archived":false,"fork":false,"pushed_at":"2023-02-03T05:50:29.000Z","size":1365,"stargazers_count":4,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-17T06:45:23.671Z","etag":null,"topics":["buttondown","buttondown-api","microbundle","nodejs","openapi","typescript"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/HugoDF.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}},"created_at":"2020-04-10T18:18:39.000Z","updated_at":"2023-01-05T19:49:00.000Z","dependencies_parsed_at":"2023-02-04T13:32:37.883Z","dependency_job_id":null,"html_url":"https://github.com/HugoDF/buttondown","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":"HugoDF/node-mit-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HugoDF%2Fbuttondown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HugoDF%2Fbuttondown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HugoDF%2Fbuttondown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HugoDF%2Fbuttondown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HugoDF","download_url":"https://codeload.github.com/HugoDF/buttondown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243989109,"owners_count":20379648,"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":["buttondown","buttondown-api","microbundle","nodejs","openapi","typescript"],"created_at":"2024-10-10T12:11:04.893Z","updated_at":"2025-03-19T11:31:18.244Z","avatar_url":"https://github.com/HugoDF.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![E2E Tests](https://github.com/HugoDF/buttondown/workflows/E2E%20Tests/badge.svg) ![Build](https://github.com/HugoDF/buttondown/workflows/Build%20\u0026%20test/badge.svg)\n\nJavaScript/TypeScript (Node.js) [Buttondown](https://buttondown.email) API wrapper.\n\n[Buttondown API](https://api.buttondown.email/v1/schema)\n\n**This library allows you to quickly and easily use the Buttondown API v1 via Node.js.**\n\nThis project is not officially affiliated with Buttondown, it's maintained by community members. For any feedback, questions or issues, please create [issues](https://github.com/HugoDF/buttondown/issues) and [pull requests](https://github.com/HugoDF/buttondown/blob/master/README.md#contributing) or merely upvote or comment on existing issues or pull requests.\n\n# Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [Installation](#installation)\n  - [Prerequisites](#prerequisites)\n  - [Obtain an API Key](#obtain-an-api-key)\n  - [Setup Environment Variables](#setup-environment-variables)\n  - [Install Package](#install-package)\n- [Quick Start, Create a Draft](#quick-start-create-a-draft)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n  - [Requirements](#requirements)\n  - [Setup](#setup)\n  - [npm scripts](#npm-scripts)\n  - [Partial generated TypeScript SDK using the OpenAPI schema](#partial-generated-typescript-sdk-using-the-openapi-schema)\n- [About](#about)\n  - [Acknowledgments](#acknowledgments)\n- [LICENSE](#license)\n\n# Installation\n\n## Prerequisites\n\n- Node.js version 10 or 12\n- A Buttondown account, [sign up for free](https://buttondown.email/register?source=buttondown-nodejs) free for your first thousand subscribers or check out [the pricing page](https://buttondown.email/pricing?source=buttondown-nodejs).\n\n## Obtain an API Key\n\nGrab your API Key from the [Buttondown Setting Page](https://buttondown.email/settings).\n\n## Setup Environment Variables\n\nDo not hardcode your [Buttondown API Key](https://buttondown.email/settings) into your code. Instead, use an environment variable or some other secure means of protecting your Buttondown API Key. Following is an example of using an environment variable.\n\nUpdate the development environment with your [BUTTONDOWN_API_KEY](https://buttondown.email/settings), for example:\n\n```bash\necho \"export BUTTONDOWN_API_KEY='YOUR_API_KEY'\" \u003e buttondown.env\necho \"buttondown.env\" \u003e\u003e .gitignore\nsource ./buttondown.env\n```\n\n## Install Package\n\nThe following recommended installation requires [npm](https://npmjs.org/). If you are unfamiliar with npm, see the [npm docs](https://npmjs.org/doc/). Npm comes installed with Node.js since node version 0.8.x, therefore, you likely already have it.\n\n```sh\nnpm install --save buttondown\n```\n\nYou may also use [yarn](https://yarnpkg.com/en/) to install.\n\n```sh\nyarn add buttondown\n```\n\n\u003ca name=\"quick-start\"\u003e\u003c/a\u003e\n# Quick Start, Create a Draft\n\nThe following is the minimum needed code to create a new draft email. Use this example, and modify the `to` and `from` variables:\n\nFor more complex use cases, please see [USE_CASES.md](./USE_CASES.md).\n\n```js\nconst buttondown = require('buttondown');\nbuttondown.setApiKey(process.env.BUTTONDOWN_API_KEY);\nconst draft = {\n  subject: 'Creating a new Buttondown draft',\n  body: '\u003cstrong\u003eand easy to do from Node.js\u003c/strong\u003e',\n};\n//ES6\nbuttondown.drafts.create(draft)\n  .then(() =\u003e {}, error =\u003e {\n    console.error(error);\n\n    if (error.response) {\n      console.error(error.response.body)\n    }\n  });\n//ES8\n(async () =\u003e {\n  try {\n    await buttondown.drafts.create(draft);\n  } catch (error) {\n    console.error(error);\n\n    if (error.response) {\n      console.error(error.response.body)\n    }\n  }\n})();\n```\n\nAfter executing the above code, you should have a draft in your Buttondown account. You view it [in the UI](https://buttondown.email/emails/drafts).\n\n# Roadmap\n\nIf you are interested in the future direction of this project, please take a look at the open [issues](https://github.com/HugoDF/buttondown/issues) and [pull requests](https://github.com/HugoDF/buttondown/pulls). I would love to hear your feedback!\n\n# Contributing\n\n## Requirements\n\n- Node 10\n- Yarn 1.x or npm\n\n## Setup\n\n1. Clone the repository\n2. Run `yarn` or `npm install` installs all required dependencies.\n3. Run `yarn build` to build from TypeScript to common JavaScript distribution formats.\n4. Run `yarn test` to run all tests :D.\n\n## npm scripts\n\n\u003e Equivalent `npm run \u003cscript\u003e` should also work\n\n- `yarn test` run tests against **built output** with [ava](https://github.com/avajs/ava). **Important**: runs against build output so run `yarn build` beforehand.\n- `yarn build` run build from TypeScript to UMD, CJS, ESM with [microbundle](https://github.com/developit/microbundle)\n- `yarn watch` runs build in watch mode with [microbundle](https://github.com/developit/microbundle)\n- `yarn lint` will lint all of the files with [xo](https://github.com/xojs/xo)\n- `yarn format` will run lint with `--fix` option on all the examples files (and tests).\n- `yarn release`, run clean, production build and release with `np`.\n\n## Partial generated TypeScript SDK using the OpenAPI schema\n\n\u003e The auto-generated SDK contains TS errors, eg. _gen/services/SubscribersService.ts has `email` in the list twice, however it's useful to lift typings from\n\nTo re-generate:\n\n1. Fetch the schema from the API docs\n```sh\ncurl https://api.buttondown.email/v1/schema\\?format\\=openapi \u003e\u003e schema.json\n```\n2. Convert using [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen)\n```sh\nnpx openapi-typescript-codegen --input schema.json --output ./_gen\n```\n3. Keep only the `services` folder\n```sh\nrm -rf _gen/core _gen/index.ts _gen/models\n```\n\n# About\n\nThis package is maintained by Hugo from [Code with Hugo](https://codewithhugo.com) and [Alpine.js Weekly](https://alpinejs.codewithhugo.com/newsletter).\n\n## Acknowledgments\n\n\nSpecial thanks to:\n\n- Justin Duke for creating Buttondown\n- The Twilio SendGrid team for the inspiration on how to structure this package and docs\n- The developers behind\n  - [got](https://github.com/sindresorhus/got#readme)\n  - [ava](https://avajs.dev)\n  - [esm](https://github.com/standard-things/esm#readme)\n  - [microbundle](https://github.com/developit/microbundle#readme)\n  - [nock](https://github.com/nock/nock#readme)\n  - [np](https://github.com/sindresorhus/np#readme)\n  - [xo](https://github.com/xojs/xo#readme)\n\n# LICENSE\n\nCode is licensed under the [MIT License](./LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhugodf%2Fbuttondown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhugodf%2Fbuttondown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhugodf%2Fbuttondown/lists"}