Skip to content
  1. Blog
  2. API

Custom Email Notifications Using AWS SES and the BoldSign API

TL;DR: You can send every eSignature email from your own Amazon Simple Email Service (SES) account instead of ours. Turn off our emails when you send the document, then let webhooks tell your app when to email each signer a signing link. Our eSignature API page shows what else the API covers.

Your product already sends email from its own address, with its own layout and tone. A signature request from another sender can look out of place, and some signers may skip it.

Custom notifications keep every message in your voice. This guide builds the flow in ASP.NET Core with our software development kit (SDK) for .NET, Amazon Web Services (AWS) SES and the MimeKit library.

What are custom email notifications for eSignature?

Custom email notifications are signing emails that your app writes and sends, while we still host the document and the signing page. You control the sender, the subject, the wording and the timing.

Think of a letter sent through a courier. We pack the parcel and track it, while your app writes the note on top and hands it over.

How does the custom email flow work?

Your app sends the document with our emails off, then reacts to webhook events. A webhook is a message we post to your server when something happens to a document.

  1. Send the document with DisableEmails set to true and a signing order.
  2. Receive the Sent event, then email the first signer a signing link.
  3. Receive the Signed event, then email the next signer in the order.
  4. Receive the Completed event, then email everyone the signed document.

What do you need before you start?

Have these ready before you write any code:

  • Basic knowledge of ASP.NET Core and C#.
  • An AWS account with SES turned on, plus its Access Key ID and Secret Access Key.
  • Visual Studio or Visual Studio Code with the ASP.NET Core SDK installed.
  • A free API sandbox account and an API key.

You find your key on the API Key page in the web app. Our API key documentation explains how to create one.

How do you set up the .NET app?

Create a web app, then add three packages. The demo uses ASP.NET Core, but any language and framework that can call a web API will work.

Create the app with the following command.

dotnet new webapp --framework "net6.0" -o AWSMailMerge

Install the BoldSign API, AWS simple email and MimeKit packages. BoldSign.Api sends and tracks the document, AWSSDK.SimpleEmail sends the mail, and MimeKit builds each message.

dotnet add package BoldSign.Api
dotnet add package AWSSDK.SimpleEmail
dotnet add package MimeKit

How do you add BoldSign services through dependency injection?

Register an API client with the API base address and your API key. Your controllers then receive the document client by injection, ready to call the BoldSign API.

Add the following code to the ConfigureServices() method in your startup.cs file.

var apiClient = new ApiClient("https://api.boldsign.com/"," ***API Key***");
services.AddSingleton(apiClient);
services.AddSingleton(new DocumentClient(apiClient));

How do you send a document with our emails turned off?

Build the send request as usual, with EnableSigningOrder and DisableEmails both set to true. We create the document and return its ID, but we send no email to any recipient.

The sample loads a PDF and adds two signers, Alex and Sam. Each signer gets one signature field and a place in the signing order.

// The document that needs to be sent for signing.
string filePath = @"Data/Sample.pdf";
List<FormField> firstSignerFormFields = new List<FormField>
{
    new FormField(
        name: "Sign",
        type: FieldType.Signature,
        pageNumber: 1,
        isRequired: true,
        bounds: new Rectangle(x: 50, y: 50, width: 150, height: 32)),
};
List<FormField> secondSignerFormFields = new List<FormField>
{
    new FormField(
        name: "Sign",
        type: FieldType.Signature,
        pageNumber: 2,
        isRequired: true,
        bounds: new Rectangle(x: 100, y: 100, width: 150, height: 32)),
};
var documentDetails = new SendForSign
{
    Title = "Sent from API SDK",
    Message = "This is document message sent from API SDK",
    EnableSigningOrder = true,
    Signers = new List<DocumentSigner>
    {
        new DocumentSigner(
            name: "Alex",
            emailAddress: "alex@example.com",
            signerOrder: 1,
            signerType: SignerType.Signer,
            privateMessage: "This is private message for signer",
            formFields: firstSignerFormFields),
        new DocumentSigner(
            name: "Sam",
            emailAddress: "sam@example.com",
            signerOrder: 2,
            signerType: SignerType.Signer,
            privateMessage: "This is private message for signer",
            formFields: secondSignerFormFields),
    },
    Files = new List<IDocumentFile>
    {
        new DocumentFilePath
        {
            ContentType = "application/pdf",
            // directly provide file path.
            FilePath = filePath,
        },
    },
    DisableEmails = true,
};
var documentCreated = await documentClient.SendDocumentAsync(documentDetails);

Note: Every option for this request is in our send document for signing reference.

How do you catch the Sent event with a webhook?

Add a webhook action that checks the request, reads the event and calls your email code. Sending is asynchronous, so the Sent event is the moment your app knows the document is ready.

Our webhooks documentation explains how to set one up. The action below answers our verification request, checks the signature with your secret key and reads the document ID and signer details from the payload.

[HttpPost]
public async Task<IActionResult> Webhook()
{
    var sr = new StreamReader(this.Request.Body);
    var json = await sr.ReadToEndAsync();
    if (this.Request.Headers[WebhookUtility.BoldSignEventHeader] == "Verification")
    {
        return this.Ok();
    }
    // TODO: Update your webhook secret key.
    var SECRET_KEY = "<<<>>>";
    try
    {
        WebhookUtility.ValidateSignature(json, this.Request.Headers[WebhookUtility.BoldSignSignatureHeader],
            SECRET_KEY);
    }
    catch (BoldSignSignatureException ex)
    {
        Console.WriteLine(ex);
        return this.Forbid();
    }
    var eventPayload = WebhookUtility.ParseEvent(json);
    var doc = eventPayload.Data as DocumentEvent;
    if (doc.DisableEmails == true)
    {
        if (eventPayload.Event.EventType == WebHookEventType.Sent)
        {
            await SendForSign(doc);
        }
    }
    return this.Ok();
}

The DisableEmails check makes sure your app only emails signers for documents where our emails are off.

How do you email the first signer through AWS SES?

Wrap SES in a few helper methods that build the message and send it. For each signer whose turn has come, the code requests an embedded signing link and puts it in the email.

The methods below do four jobs:

  1. Pick the signers who have not signed yet and whose turn it is.
  2. Request an embedded signing link for each of them.
  3. Fill an email template with the signer’s name, the signer list and the link.
  4. Send the message through SES with MimeKit.
private async Task SendForSign(DocumentEvent docDetails)
{
    List signerDetails = GetSequentialNotCompletedSigners(docDetails.SignerDetails);
    string signerList = GenerateSignerList(signerDetails);

    foreach (var signer in signerDetails)
    {
        string signerEmail = signer.SignerEmail;
        string signerName = signer.SignerName;
        string subject = "Signature Request from {signerName}";
        subject = subject.Replace("{signerName}", signerName);
        string filePath = "EmailTemplates/SendForSign.txt"; // Update the path to your file

        EmbeddedSigningLink signingLink = await documentClient
            .GetEmbeddedSignLinkAsync(docDetails.DocumentId, signer.SignerEmail).ConfigureAwait(false);

        // Customize your email body content here.
        string body = GetEmailBodyContent(signerName, signerList, signingLink.SignLink, filePath);

        // Call the method to send the email.
        await SendEmailAsync(signerEmail, subject, body);
    }
}

private string GenerateSignerList(List signerDetails)
{
    StringBuilder sb = new StringBuilder();
    foreach (var signerDetail in signerDetails)
    {
        sb.AppendLine($"{signerDetail.SignerName} ({signerDetail.SignerEmail})");
    }

    return sb.ToString();
}

private List GetSequentialNotCompletedSigners(List signerDetails)
{
    List sequentialNotCompletedSigners = new List();
    int expectedOrder = 0;

    foreach (var signer in signerDetails)
    {
        if (signer.Status == SignerStatus.NotCompleted && (signer.Order == expectedOrder || expectedOrder == 0))
        {
            sequentialNotCompletedSigners.Add(signer);
            expectedOrder = signer.Order ?? expectedOrder;
        }
    }

    return sequentialNotCompletedSigners;
}

private async Task SendEmailAsync(string recipientEmail, string subject, string body, byte[] attachment = null)
{
    AWSCredentials credentials = new BasicAWSCredentials("", "");

    using (var client = new AmazonSimpleEmailServiceClient(credentials, RegionEndpoint.USEast1)) // Replace RegionEndpoint with your desired AWS region
    {
        try
        {
            var message = new MimeMessage();
            message.To.Add(new MailboxAddress(null, recipientEmail));
            message.From.Add(new MailboxAddress("Example Team", senderEmail));
            message.Subject = subject;

            using (var stream = new MemoryStream())
            {
                var emailBody = ConvertToHtml(body, attachment);
                message.Body = emailBody.ToMessageBody();
                await message.WriteToAsync(stream).ConfigureAwait(false);
                var request = new SendRawEmailRequest
                {
                    RawMessage = new RawMessage(stream),
                };

                var response = await client.SendRawEmailAsync(request).ConfigureAwait(false);
                Console.WriteLine("Email sent! Message ID: " + response.MessageId);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine("Email sending failed. Error: " + ex.Message);
        }
    }
}

private BodyBuilder ConvertToHtml(string plainText, byte[] attachment = null)
{
    var bodyBuilder = new BodyBuilder();
    bodyBuilder.HtmlBody = $"{plainText}";

    if (attachment != null)
    {
        bodyBuilder.Attachments.Add(documentName, attachment);
    }

    return bodyBuilder;
}

private string GetEmailBodyContent(string signerName, string signerList, string signingLink, string filePath)
{
    string emailTemplate;
    using (var fs = new FileStream(filePath, FileMode.Open))
        using (var sr = new StreamReader(fs))
    {
        emailTemplate = sr.ReadToEnd();
    }

    emailTemplate = emailTemplate.Replace("[SignerName]", signerName);
    emailTemplate = emailTemplate.Replace("[DocumentList]", documentName);

    if (!string.IsNullOrEmpty(signerList))
    {
        emailTemplate = emailTemplate.Replace("[SignerList]", signerList);
    }

    if (!string.IsNullOrEmpty(signingLink))
    {
        emailTemplate = emailTemplate.Replace("[SigningLink]", signingLink);
    }

    return emailTemplate;
}

Note: Store the status of each signature request so you can track it later.

What does the signature request email template look like?

The template is a plain file with placeholders in square brackets. The code swaps [SignerName], [DocumentList], [SignerList] and [SigningLink] for real values before each send.

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <title>Signature Request</title>
    <style>
        <!-- Your css styles -->
    </style>
</head>
<body>
    <div class="container">
        <div class="header">
            <h1>Signature Request</h1>
        </div>
        <p>Dear [SignerName],</p>
        <p>You are kindly requested to sign the [DocumentList] document.</p>
        <p>The following signers need to sign this document:</p>
        <ul>
            [SignerList]
        </ul>
        <p>Please click the button below to proceed with the signing process:</p>
        <a class="button" href="[SigningLink]">Click here to sign</a>
        <p>Thank you for your cooperation.</p>
        <div class="footer">
            <p>Best regards,<br> Example Team</p>
        </div>
    </div>
</body>
</html>

How do you notify the next signer in the signing order?

Handle the Signed event in the same webhook action and call the same send method. The code emails whoever is next once a signer finishes and the document is still in progress.

var eventPayload = WebhookUtility.ParseEvent(json);
var doc = eventPayload.Data as DocumentEvent;
if (doc.DisableEmails == true)
{
    if (eventPayload.Event.EventType == WebHookEventType.Signed && doc.Status == DocumentStatus.InProgress)
    {
        await SendForSign(doc);
    }
}

The same code works for any number of signers, since the send method skips anyone who has already signed.

How do you send the completed document to every signer?

Handle the Completed event, download the signed document and attach it to a final email. The code sends that email to every signer on the document.

First, check for the Completed event and the completed status.

var eventPayload = WebhookUtility.ParseEvent(json);
var doc = eventPayload.Data as DocumentEvent;
if (doc.DisableEmails == true)
{
    if (eventPayload.Event.EventType == WebHookEventType.Completed && doc.Status == DocumentStatus.Completed)
    {
        await SendForCompleted(doc);
    }
}

Then download the document, turn it into a byte array and send it with a completion template. Keep a secure copy of the signed file on your side as well.

private async Task SendForCompleted(DocumentEvent docDetails)
{
    var downloadDocument = await documentClient.DownloadDocumentAsync(docDetails.DocumentId).ConfigureAwait(false);
    byte[] attachment = null;
    using (MemoryStream ms = new MemoryStream())
    {
        downloadDocument.CopyTo(ms);
        attachment = ms.ToArray();
    }
    foreach (var signer in docDetails.SignerDetails)
    {
        string signerEmail = signer.SignerEmail;
        string signerName = signer.SignerName;
        string subject = "Everyone has signed the document";
        string filePath = "EmailTemplates/SendForComplete.txt"; // Update the path to your file
        // Customize your email body content here.
        string body = GetEmailBodyContent(signerName, string.Empty, string.Empty, filePath);
        // Call the method to send the email.
        await SendEmailAsync(signerEmail, subject, body, attachment);
    }
}

What should you watch out for?

Your app now owns every message, so a few gaps are yours to cover. Plan for them before you go live.

  • Verify each signer’s identity before you share an embedded signing link, as our embedded signing link reference requires.
  • Handle the Declined, Revoked, Reassigned and Expired events, listed under available webhook events, with their own emails.
  • Log each SES response, since a failed send means a signer never hears about the document.

Want your own wording without running a mail service? Our guide to customizing eSignature emails in BoldSign covers that route. For text messages instead of email, see our guide to customized SMS notifications.

Which BoldSign API plan do you need, and what does it cost?

Live use of the BoldSign API, with webhooks and embedded signing links, needs the Enterprise API plan. It starts at $30 a month with 40 envelopes, and each extra envelope costs $0.75, per our pricing page in November 2026.

You can build and test the whole flow in the free sandbox first. Prices are in USD, and AWS bills your SES usage separately.

Where do you go next with custom email notifications?

Start in the sandbox, send a test document to your own inbox and watch each webhook arrive.

Frequently asked questions

Can I send BoldSign signature request emails from my own email service?

Yes. Send the document with DisableEmails set to true, then email each signer an embedded signing link from your own service, such as Amazon SES.

What does DisableEmails do in the BoldSign API?

It stops us from sending document emails to every recipient of that document. Your app then owns all the messages, from the first request to the completion email.

Which webhook events drive custom email notifications?

Three document events do most of the work. Sent starts the first request, Signed moves the request to the next signer, and Completed triggers the final email with the signed file.

How does my app know which signer to email next?

Each webhook carries the signer details with their order and status. The sample picks the signers who have not completed yet and emails the ones whose turn has come.

Are documents signed through an embedded signing link legally binding?

Yes, when your app verifies the signer's identity before it shares the link. Our audit trail notes the embedded link, and you keep your own record of that check.

Can I attach the signed PDF to the completion email?

Yes. Download the completed document through the API, read it into a byte array and add it as an attachment before your email service sends the message.

Do I have to use AWS SES for custom email notifications?

No. Our side only supplies the webhook events and the signing links. Any email service or mail server your app can call can deliver them.

Can I test custom email notifications for free?

Yes. The free API sandbox needs no credit card, so you can run the whole flow first. Sandbox documents carry a test watermark and are deleted after 14 days.

Ramesh Thangaraj

Ramesh is a passionate Product Manager at BoldSign with 6+ years of hands-on experience in software development. He excels in web technologies, mastering .NET and harnessing Vue.js. His full-stack expertise enables him to deliver innovative solutions. Ramesh thrives in cross-functional teams, driving projects forward with his strategic mindset. Connect with him on LinkedIn.

More posts by Ramesh Thangaraj
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required