Send a batch of Docusign envelopes from a Google Sheet

Build me a Docusign send desk app: an internal tool that turns a Google Sheet into a batch of Docusign envelopes, with a validate-before-you-send review step and a live tracking view afterwards. The users are ops and HR people sending the same document to fifty or a hundred people at once, like annual policy acknowledgements, contractor agreements, or W-9 collection. Today they have to download a sample CSV from Docusign, fill it in offline, re-import it and hope it took. This app replaces that round trip.

Home screen: a list of past batches, newest first, each showing the template name, the source sheet and tab, when it was sent, who sent it, and a compact status roll-up (sent, completed, declined, failed). Clicking a batch opens its tracking view. A prominent New batch button starts the send flow. The flow is a stepper with four steps: Template, Source, Mapping, Review.

Step 1, Template. A dropdown of the account's Docusign templates, populated by a handler calling Docusign List Templates. Page through the results with the count and start_position parameters so accounts with many templates are fully covered, and let the user filter the dropdown by typing. When a template is selected, call Docusign Get Template for that template ID and hold on to its structure: the recipient roles (roleName, plus the role's routing order) and the tabs defined on each role, keyed by tabLabel and tab type (textTabs, numberTabs, dateTabs, checkboxTabs, listTabs, and so on). Show a small summary of the chosen template: document names, the roles it expects, and how many fill-in fields each role has.

Step 2, Source. The user pastes a Google Sheets URL or spreadsheet ID. Parse the ID out of the URL. Call Google Sheets Get Spreadsheet to list the tabs and show them as a dropdown. Once a tab is chosen, read the data with Google Sheets Get Values over that tab's range, treating the first row as headers. If the sheet is large, read it in A1 subranges rather than one enormous request, or use Batch Get Values to combine range reads into a single call. Show a preview of the first ten data rows and the detected row count so the user can confirm they picked the right tab.

Step 3, Mapping. A two column mapping screen. On the left, everything the template needs, grouped by recipient role: the role's recipient name, the role's email, and each of that role's fill-in fields listed by its tab label. On the right, a dropdown per item listing the spreadsheet's column headers, plus a Static value option for fields that are the same for every recipient (for example a policy year) and a Leave blank option. Auto-suggest a mapping on first load by fuzzy matching header names to role and tab labels (a header called Email maps to the signer email, Full Name to the signer name, Manager to a tab labelled Manager), and let the user override every suggestion. Mark which template fields are required so the review step can validate them. Persist the mapping keyed by template ID plus spreadsheet ID plus tab name, so the next batch from the same sheet opens prefilled.

Step 4, Review. This is the heart of the app and where the value sits. Render a table with one row per spreadsheet row, showing the resolved recipient name, email, role, and every mapped field value exactly as it will be sent. Run inline validation on every row and show the problems in the row itself, not in a summary banner: missing email, malformed email address, blank value for a field the template marks required, and duplicate recipient (the same email address appearing more than once in this batch). Separate blocking errors from warnings. Give every row a checkbox, checked by default, and auto-uncheck rows with blocking errors. Include a header bar with counts (ready to send, has warnings, blocked, unchecked), quick filters to show only problem rows, bulk check and uncheck, and a Reload from sheet button so the user can fix the spreadsheet in another tab and pull the corrections in without restarting the flow. The Send button shows the exact count, for example Send 87 envelopes, and asks for a confirmation.

Sending. Important constraint: there is no bulk send list operation available, so do not attempt to create a bulk send list or a bulk send request. The app sends by looping Docusign Create Envelope once per approved row. Each call uses the template ID, status set to sent so it goes out immediately, and templateRoles carrying the role name, recipient name, recipient email, and the mapped tab values for that role (text tab values keyed by tabLabel, and the matching structure for other tab types). Throttle the loop to respect Docusign's limits: roughly 500 calls per 30 seconds burst and 3,000 calls per hour per account. Pace with a rolling window budget set safely under the burst limit (around 400 per 30 seconds) with a small number of concurrent requests rather than firing everything at once. On HTTP 429, back off exponentially with jitter and retry that row a few times before marking it failed. While the loop runs, show a progress bar with a live count and a per row result marker: success with the returned envelope ID, or failure with the error message from Docusign. A failure on one row never stops the batch. Persist each row's outcome as it completes so a page refresh mid-send does not lose the record, and so re-running a batch never re-sends a row that already produced an envelope ID.

Tracking. When the send loop finishes, the batch stays on screen and becomes a tracking view rather than disappearing. It refreshes envelope state on an interval and on a manual Refresh button, using Docusign List Envelopes filtered to the batch's envelope IDs and send date to pull current envelope status in bulk, and Docusign List Recipients per envelope to get per recipient detail (recipient status, when they were delivered to, when they signed). Fall back to Docusign Get Envelope for a single envelope when the user drills into one row. Translate the raw states into columns a non-technical user reads at a glance: Sent, Opened, Signed, Declined, Voided, Bounced (a recipient whose status came back as autoresponded), and Failed to send. Show a summary strip at the top with the counts and a completion percentage, and let the user filter to Not signed yet so chasing people is one click. Include a link out to the envelope in Docusign on each row.

Write-back. The spreadsheet stays the record of truth, so after sending, and again on every tracking refresh, write results back to the source tab with Google Sheets Update Values. Write the envelope ID, the current status, and a last-updated timestamp into columns on the same row the recipient came from, matched by the original row index. If the destination columns do not exist yet, add the header labels (Envelope ID, Docusign Status, Last Updated) at the first free columns and remember which columns those are for this batch. Group the writes into as few calls as possible with Batch Update Values so the app stays well inside Google's write quota of about 60 write requests per minute per user, and never write more often than the tracking refresh interval. Rows that failed to send get the failure reason written back too, so the sheet shows the whole picture.

General notes: batches, their row-level results, and the saved column mappings all persist, so a user can close the app and come back to a batch days later and it still tracks. Keep the review table and the tracking table dense and scannable, since these are hundred-row screens. Show clear empty states, and if the Docusign or Google Sheets connection is missing or the sheet is not accessible, say so plainly at the step where it matters instead of failing silently.