Formed in 2009, the Archive Team (not to be confused with the archive.org Archive-It Team) is a rogue archivist collective dedicated to saving copies of rapidly dying or deleted websites for the sake of history and digital heritage. The group is 100% composed of volunteers and interested parties, and has expanded into a large amount of related projects for saving online and digital history.
Lob a bunch
Some times you want to send more then one postcard/letter/check at a time. Now you can.
Table of contents
- Installation
- Setup
- Basic Example
- Sending mail
- Creating addresses and bank accounts
- Handling responses
- Handling errors
- Testing
Installation
Install this the usual npm way. You need to have the node Lob library installed separately.
npm install lob-a-bunch --save
Setup
lob-a-bunch will modify an existing Lob object to give it the batching functionality.
const lobABunch = require('lob-a-bunch');
const Lob = require('lob')('YOUR API KEY');
lobABunch(Lob);Safe mode
To lessen the chance of conflicts or incompatibilities with the lob library use safe mode.
When using the batch functionality use batch instead of create with same payload.
lobABunch.safe(Lob);
Lob.addresses.batch([ ... ]) // instead of Lob.addresses.create
.then(() => {});
Basic Example
Now we're all set to use an array of recipients instead of just one.
Lob.postcards.create({
description: 'Demo Postcard job',
to: [ {
name: 'Harry Potter',
address_line1: '4 Privet Drive',
address_city: ', Elkridge',
address_state: 'MD',
address_zip: '21075',
overrides: {
data: { name: 'Harry' }
}
}, {
name: 'Ron Weasley',
address_line1: '123 Main Street',
address_city: 'Mountain View',
address_state: 'CA',
address_zip: '94041',
overrides: {
data: { name: 'Ron' }
}
} ],
front: '<html style="padding: 1in; font-size: 50;">Front HTML for {{name}}</html>',
back: '<html style="padding: 1in; font-size: 20;">Back HTML for {{name}}</html>',
data: { name: 'my favorite person' }
}).then((results) => {
console.log(results);
}).catch((err) => {
console.log(err);
});This should give use something like this back.
{ "rejected_count": 0,
"accepted_count": 2,
"batch_count": 0,
"data":
[ { "id": "psc_dceaa5c60f3bc71d",
...
"object": "postcard" },
{ "id": "psc_1c73d1a31c03e5f9",
...
"object": "postcard" } ] }Sending mail
Important: The documentation is written for postcards but works identically with both letters and checks.
postcard.create(payload[, config, callback]) -> Promise
letters.create(payload[, config, callback]) -> Promise
checks.create(payload[, config, callback]) -> Promise
payload- See the docs for all the arguments
- Type:
Object - Required:
true
payload.to- Type:
Array|Object|String - Description:
tois 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. - Required:
true
- Type:
payload.to[x].overrides- Type:
Object - 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. - Required:
false
- Type:
config- Type:
Object - Description: Configuration for the batch requesting.
- Required:
false
- Type:
config.every- Type:
Function - Description: A function called with the
errorandresultafter each request is fulfilled. - Required:
false
- Type:
config.max_requests- Type:
Number - Description: The maximum number of requests that can be open at once. (This will never be larger then the number of recipients)
- Default:
25 - Required:
false
- Type:
callback- Type:
Function - Description: A function called after all the requests have been fulfilled.
- Required:
false
- Type:
Creating addresses and bank accounts
Important: The documentation is written for addresses but works identically with bank accounts.
addresses.create(payload[, config, callback]) -> Promise
bankAccounts.create(payload[, config, callback]) -> Promise
payload- See the docs for all the arguments
- Type:
Array|Object - Required:
true - An a single address object or an array of address objects
config- Type:
Object - Description: Configuration for the batch requesting.
- Required:
false
- Type:
config.every- Type:
Function - Description: A function called with the
errorandresultafter each request is fulfilled. - Required:
false
- Type:
config.max_requests- Type:
Number - Description: The maximum number of requests that can be open at once. (This will never be larger then the number of recipients)
- Default:
25 - Required:
false
- Type:
callback- Type:
Function - Description: A function called after all the requests have been fulfilled.
- Required:
false
- Type:
Handling Responses
If 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.
Response objects contain the listed values when given in the Promise or callback. The order of the responses is not guaranteed.
err.rejected_count- The number of requests that failed for any reason except rate limiting.err.accepted_count- The number of requests that succeeded.err.batch_count- The number of times the rate limit was hit and waited on.err.errors- An array of all the errors that came back. The errors are passed directly from lob with the added value of_requestwhich has the object sent to the API. This key only exists if there is one or more errors.err.data- An array of all the successful responses. These are purely passed through from lob.
Handling Errors
The 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.
Lob.postcards.create(...)
.catch((err) => {
console.log(err.results); // outputs { rejected_count: 3, ... }
});