{"id":20917962,"url":"https://github.com/avigoldman/lob-a-bunch","last_synced_at":"2025-12-27T21:04:51.556Z","repository":{"id":81614983,"uuid":"89390568","full_name":"avigoldman/lob-a-bunch","owner":"avigoldman","description":"Some times you want to send more then one postcard/letter/check at a time. Now you can.","archived":false,"fork":false,"pushed_at":"2017-04-26T17:48:12.000Z","size":15,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-19T16:48:57.429Z","etag":null,"topics":["api","batch","bunch","lob","multiple","node","postcards"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/avigoldman.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}},"created_at":"2017-04-25T17:55:30.000Z","updated_at":"2021-06-10T15:52:57.000Z","dependencies_parsed_at":"2023-03-07T06:00:17.668Z","dependency_job_id":null,"html_url":"https://github.com/avigoldman/lob-a-bunch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avigoldman%2Flob-a-bunch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avigoldman%2Flob-a-bunch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avigoldman%2Flob-a-bunch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avigoldman%2Flob-a-bunch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avigoldman","download_url":"https://codeload.github.com/avigoldman/lob-a-bunch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243312904,"owners_count":20271160,"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":["api","batch","bunch","lob","multiple","node","postcards"],"created_at":"2024-11-18T16:36:44.154Z","updated_at":"2025-12-27T21:04:51.491Z","avatar_url":"https://github.com/avigoldman.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lob a bunch\n\nSome times you want to send more then one postcard/letter/check at a time. Now you can.\n\n\n## Table of contents\n* [Installation](#installation)\n* [Setup](#setup)\n* [Basic Example](#basic-example)\n* [Sending mail](#sending-mail)\n* [Creating addresses and bank accounts](#creating-addresses-and-bank-accounts)\n* [Handling responses](#handling-responses)\n* [Handling errors](#handling-errors)\n* [Testing](#testing)\n\n## Installation\n\nInstall this the usual npm way. You need to have the [node Lob library](https://github.com/lob/lob-node/) installed separately.\n\n```\nnpm install lob-a-bunch --save\n```\n\n## Setup\n\n`lob-a-bunch` will modify an existing Lob object to give it the batching functionality.\n\n```js\nconst lobABunch = require('lob-a-bunch');\nconst Lob = require('lob')('YOUR API KEY');\n\nlobABunch(Lob);\n```\n\n### Safe mode\n\nTo lessen the chance of conflicts or incompatibilities with the lob library use safe mode.\n\nWhen using the batch functionality use `batch` instead of `create` with same payload.\n\n```\nlobABunch.safe(Lob);\n\nLob.addresses.batch([ ... ]) // instead of Lob.addresses.create\n\t.then(() =\u003e {});\n```\n\n\n## Basic Example\n\nNow we're all set to use an array of recipients instead of just one.\n\n```js\nLob.postcards.create({\n  description: 'Demo Postcard job',\n  to: [ {\n      name: 'Harry Potter',\n      address_line1: '4 Privet Drive',\n      address_city: ', Elkridge',\n      address_state: 'MD',\n      address_zip: '21075',\n      overrides: {\n        data: { name: 'Harry' }\n      }\n    }, {\n      name: 'Ron Weasley',\n      address_line1: '123 Main Street',\n      address_city: 'Mountain View',\n      address_state: 'CA',\n      address_zip: '94041',\n      overrides: {\n        data: { name: 'Ron' }\n      }\n    } ],\n  front: '\u003chtml style=\"padding: 1in; font-size: 50;\"\u003eFront HTML for {{name}}\u003c/html\u003e',\n  back: '\u003chtml style=\"padding: 1in; font-size: 20;\"\u003eBack HTML for {{name}}\u003c/html\u003e',\n  data: { name: 'my favorite person' }\n}).then((results) =\u003e {\n  console.log(results);\n}).catch((err) =\u003e {\n  console.log(err);\n});\n```\n\nThis should give use something like this back.\n\n```js\n{ \"rejected_count\": 0,\n  \"accepted_count\": 2,\n  \"batch_count\": 0,\n  \"data\":\n   [ { \"id\": \"psc_dceaa5c60f3bc71d\",\n       ...\n       \"object\": \"postcard\" },\n     { \"id\": \"psc_1c73d1a31c03e5f9\",\n       ...\n       \"object\": \"postcard\" } ] }\n```\n\n\n## Sending mail\n**Important:** The documentation is written for postcards but works identically with both *letters* and *checks*.\n\n#### `postcard.create(payload[, config, callback])` -\u003e `Promise`\u003cbr\u003e`letters.create(payload[, config, callback])` -\u003e `Promise`\u003cbr\u003e`checks.create(payload[, config, callback])` -\u003e `Promise`\n* `payload`\n\t* See the [docs](https://lob.com/docs/node#postcards_object) for all the arguments\n\t* Type: `Object`\n\t* Required: `true`\n* `payload.to`\n\t* Type: `Array|Object|String`\n\t* Description: `to` is either an single recipient (the default functionality) or an array of recipients. Recipients can be an object with the correct address parameters or a string ID of an pre-existing address.\n\t* Required: `true`\n* `payload.to[x].overrides`\n\t* Type: `Object`\n\t* Description: An object of values to be merged the payload. Use this to modify the `message`, `data`, or any other value on a recipient basis.\n\t* Required: `false`\n* `config`\n\t* Type: `Object`\n\t* Description: Configuration for the batch requesting.\n\t* Required: `false`\n* `config.every`\n\t* Type: `Function`\n\t* Description: A function called with the `error` and `result` after each request is fulfilled.\n\t* Required: `false`\n* `config.max_requests`\n\t* Type: `Number`\n\t* Description: The maximum number of requests that can be open at once. (This will never be larger then the number of recipients)\n\t* Default: `25`\n\t* Required: `false`\n* `callback`\n\t* Type: `Function`\n\t* Description: A function called after all the requests have been fulfilled.\n\t* Required: `false`\n\n\n## Creating addresses and bank accounts\n**Important:** The documentation is written for addresses but works identically with *bank accounts*.\n\n#### `addresses.create(payload[, config, callback])` -\u003e `Promise`\u003cbr\u003e`bankAccounts.create(payload[, config, callback])` -\u003e `Promise`\n* `payload`\n\t* See the [docs](https://lob.com/docs/node#addresses_create) for all the arguments\n\t* Type: `Array|Object`\n\t* Required: `true`\n\t* An a single address object or an array of address objects\n* `config`\n\t* Type: `Object`\n\t* Description: Configuration for the batch requesting.\n\t* Required: `false`\n* `config.every`\n\t* Type: `Function`\n\t* Description: A function called with the `error` and `result` after each request is fulfilled.\n\t* Required: `false`\n* `config.max_requests`\n\t* Type: `Number`\n\t* Description: The maximum number of requests that can be open at once. (This will never be larger then the number of recipients)\n\t* Default: `25`\n\t* Required: `false`\n* `callback`\n\t* Type: `Function`\n\t* Description: A function called after all the requests have been fulfilled.\n\t* Required: `false`\n\n\n## Handling Responses\n\nIf a single object is passed in `payload.to` for sending mail or in creating an address or bank account the normal response is given. If an array is given in its place the response is as follows.\n\nResponse objects contain the listed values when given in the Promise or callback. The order of the responses is not guaranteed.\n\n* `err.rejected_count` - The number of requests that failed for any reason except rate limiting.\n* `err.accepted_count` - The number of requests that succeeded.\n* `err.batch_count` - The number of times the rate limit was hit and waited on.\n* `err.errors` - An array of all the errors that came back. The errors are passed directly from lob with the added value of `_request` which has the object sent to the API. This key only exists if there is one or more errors.\n* `err.data` - An array of all the successful responses. These are purely passed through from lob.\n\n\n## Handling Errors\n\nThe batch create functions will throw back an error only if no requests are successful and there is at least one error. The error has a `results` key which is identical to the response outline above.\n\n```\nLob.postcards.create(...)\n.catch((err) =\u003e {\n\tconsole.log(err.results); // outputs { rejected_count: 3, ... }\n});\n```\n\n\n## Testing","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favigoldman%2Flob-a-bunch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favigoldman%2Flob-a-bunch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favigoldman%2Flob-a-bunch/lists"}