Sending a ton of DocuSign envelopes all
at once can be a huge hassle. Join us
today as we talk to Robert Reynolds
about Bulk Send using v2.1 of our
eSignature API on this episode of
Developer Deep Dive.
Hi my name is Matthew Roknich,
Developer Evangelist at DocuSign. As you
might notice the backdrop is little bit
different. We snuck into the official
DocuSign studios after hours and I'm
here with Robert Reynolds, Engineering
Manager responsible for maintaining some
of our public-facing APIs. Robert it is
great to have you on the show. >> Yeah
thank you for having me excited to be here.
>> So Robert tell us a bit about the
inspiration behind Bulk Send. >> Well this
feature really was requested by our
customers. When it was first introduced a
few years ago they were really excited
about the positive impact this was going
to have on their productivity. At the
time preparing and sending a single
envelope with the web app or the API
worked great.
However, sending the same envelope out to
hundreds of recipients was incredibly
time consuming. If you were using the UI
it was a manual effort. If you remember
the developer community you're
essentially calling create envelope
within a loop. With the new iteration of
Bulk Send you as a developer can easily
send the same document to a large number
of recipients. You simply set up your
document once, create your mailing list,
and then you send your envelope using
that list. >> Fantastic, so for our dev
community, what are some of the
limitations of that first version of Bulk
Send? >> Well we really built the feature out
first with the UI in mind. As a
consequence it was recipient-based and
it was uploading a CSV file. You as a
developer aren't interested in posting
CSV files. It had the severe limitation
that it was only one recipient. We also
lacked explicit support for document
custom fields or populating your
envelope custom fields and some of the
features like SMS auth, embedded sending
was a big one that it didn't support.
There wasn't a way to supply your
captive recipient IDs. Those were some of
the big ones. >> Great, now that we've
upgraded to v2.1 of the eSignature
API, what capabilities specifically have
been added for Bulk Send? >> With v2.1
we've taken a step back looked at
all the feedback and we've taken a
completely new approach to how we expose
Bulk Send. So we have a new API BulkSendList
endpoint that is list-focused so
you can now persist your list with
DocuSign. You can come back, reuse it,
update it, use it again and again.
There is explicit support for populating
your document custom fields and your
envelope custom fields. We've just made
it incredibly easy to use so there's
not really much paradigm to learn. You
create your draft envelopes just as you
normally would. You create your list then
you combine the two and there's your
Bulk Send. >> It sounds incredibly easy to
use. What about limitations? What are the
default limitations using this new Bulk
Send? >> So resources aren't infinite so to
keep the system snappy and working
efficient for all our customers we do
cap our Bulk Send mailing lists at a
thousand entries and you're limited to
two thousand envelopes that are in
flight at any one time. >> So it's easy to
talk about Bulk Send from the
perspective of theoretical twenty
thousand feet up. Let's talk about an
actual real-world use case. So in this
use case I'm gonna play the role of an
elementary school teacher who needs to
send out a bunch of permission slips to
parents and you as a parent know that
oftentimes permission slips that our
paper end up being lost or stolen or
eaten or something?
So how as a developer can we solve this
problem for a elementary school teacher?
>> So this is a classic example where you
would use Bulk Send. You have the same
document, your permission slip that you
want to send out to all the parents of
all the kids in the class and you know
even perhaps maybe you beyond the
permission slip maybe you have a waiver
that using our supplemental docs you can
record the fact that they've accepted
and reviewed the terms and conditions.
>> Let's actually see this example in
Postman if you could show us the steps. >> Yeah.
>> Great. >> Let's dive into it. Here in step
one what we're gonna do is we're just
gonna create a draft envelope. This is
nothing new, just however you're used to
creating your draft envelopes. I'm gonna
happen to use a template here for ease
of demonstration purposes and here we're
using our connect notifications. So you
can see here I'm providing a callback
URL which is really handy I can provide
query string parameters with any data in
the query string that I like. I'm
subscribing to two events here. Sent and
completed. We'll get into this more
later to show how we use this, but
I'll point that out right now.
So here we're gonna call post on the
envelope and I get back an envelope ID.
Great.
So the next thing to do is we want to
create our list. This is our new endpoint.
We're going to post a list. We give our list
a name and then our request consists of
an array of entries. This request happens
to have 8 entries in it so I'm going to
generate 8 envelopes. In my entry here
I'm specifying a subject, which is
optional I can use the default in the
draft envelope or I can give a custom
one here for this envelope. We're sending
here to Martha Stewart and here you can
see we're supplying some tab values that
I know are on our envelope and here's
the second recipient on that envelope
John Candy in the teacher role and then
it just repeats for each entry. So we
call post on this list and what I get
back here is a list ID. So now that we
have these two components our draft
envelope ID and our list ID we can
combine those two to generate a Bulk
Send. We're gonna call the send
action, the list ID is here in the URL.
And by the way I have a little script
that's running that it extracts that
list ID from the response and populates
my environment variable so we're using
it here. And here in the body of the request
is the envelope ID that came from that
first draft we created.
It's called envelope or template ID,
because you can use a template here
directly if you want. Great we're
going to now send that and off goes our
Bulk Send. >> Great so as an elementary
school teacher I want to track the
status of the envelopes that we've sent
to this batch, how can I do that?
>> Ok great question. I'm gonna give you two
ways to do that. We can retrieve status
on the batch ID here in the URL. Let's
request that and I can see the important
part here is we have six that have been
sent and two are still in the queue.
Alright let's refresh this request. It's
an asynchronous process so these are
processing and great we're done now so
eight have been sent. So the limitation
on this approach is you're kind of
waiting for the whole batch to be
completed you don't really have any idea
from this which envelopes have been sent.
>> Right. >> So this is where the power of
Connect comes in. So we we provided this
callback URL
I mentioned earlier. Let's hop over
here to webhook which is my listener. We
see we have new requests come in and
here's that URL with the query string
data I'd put in there and so if I
look at the details of the request I can
see who the recipients were and that
their status is sent right here. So in my
own application if I have a next step in
the process I can kick off and take that
on right now. And so if we go full circle
on that this is my inbox out here for
Martha Stewart.
She has an email to come sign this
permission slip form, she clicks the link,
she goes into signing. >> So as a parent
here, this is what I'm going to see? >> Yep.
So here is the parent. We can see
here we provided a custom note value. The
student's name is Rusty and why is Rusty
always late to class? So she's
going sign, adopt and sign, initial and
and here I'm gonna show off our
supplemental docs, right? Maybe
beyond the form there's a terms and
conditions or some kind of legal
disclaimer that you want them to
accept. So now you have electronic
evidence that they have accepted those
terms and conditions. Finish. Now
this envelope has been completed. If we
come back out to webhook we will see our
call back again. Okay and here we go, I
just received the request let's look at
the details. And there we are. We can see
that Martha Stewart has completed the
envelope. >> Great. >> So that's it, easy as
1-2-3. Create your draft, create your
mailing list, send it. >> This was great,
Robert and that's all the time we have.
Join us next month when Caly Moss
speaks with Joe Cocco about leveraging
React components to ensure consistent
style across our user interface.
If you liked that video be sure to
subscribe to our channel for the latest
DocuSign developer content. If you want
to see a specific topic in a future
video comment below. For everything else
visit the DocuSign Developer Center.
[Music]