Skip to content
  1. Blog
  2. API

How to Detect Email and SMS Delivery Failure in eSignature Code

TL;DR: An unsigned request is sometimes a delivery problem, not a slow signer. Emails bounce or land in spam, and carriers drop text messages, all after your API call succeeds. Our eSignature API sends a DeliveryFailed webhook event so your code can act on a failed email.

A signer never opens the signature request. Days later, the sender checks the status and still sees it in progress, because the request went out but never arrived.

That gap between sent and delivered is where many requests stall. This guide covers why email and text messages fail, and how to catch the failure in code.

What is a delivery failure in an eSignature workflow?

A delivery failure happens when we send a signature request, but it does not reach the signer’s inbox or phone. Your API call still succeeds, so nothing in your app looks wrong.

Think of posting a birthday card. The post office takes it, so you count it as sent. If the address is wrong, the card comes back weeks later, or not at all.

Email and text messages work the same way. The send step and the delivery step are separate, and each one can fail on its own.

For a business, a failed delivery looks like an idle signer. A vendor agreement or an onboarding form sits unsigned, and the signer may not know it exists.

Why does a sent signature request never arrive by email?

Most email failures are bounces, and they come in two kinds. A hard bounce is permanent, while a soft bounce is temporary.

What is a hard bounce?

A hard bounce means the message can never arrive at that address. The address does not exist, the domain is gone, or the mailbox was deleted.

Sending again does nothing. The sender has to correct the address before the request can go through.

What is a soft bounce?

A soft bounce is a short-term problem, such as a full inbox or a busy mail server. Many systems, including Amazon Simple Email Service (SES), try again for a period before they give up.

Mail servers mark the two kinds with reply codes. A code in the 4xx range points to a temporary failure, and a 5xx code points to a permanent one. Some providers hide these codes, but the split is still useful to know.

How does email authentication decide whether the email is trusted?

Receiving mail servers check three sender records before they trust a message. A message can leave our servers and still land in spam when these checks fail.

  • Sender Policy Framework (SPF) lists the mail servers allowed to send for a domain.
  • DomainKeys Identified Mail (DKIM) adds a digital signature that proves the message was not changed.
  • Domain-based Message Authentication, Reporting and Conformance (DMARC) tells servers what to do when checks fail.

Each record lives in the domain’s Domain Name System (DNS) settings. A wrong record may give no bounce at all. The message just lands in spam, and nobody hears about it.

What changes when you send from your own domain?

You set up a custom sending domain through a support ticket with us. We send you the DKIM and Return-Path records, and you add them to your DNS.

Plan for that ticket step. The domain goes live only after our support team verifies it, so it does not switch on the moment you save the settings.

Why do SMS signature requests fail to deliver?

Text messages fail at the phone carrier, not at an inbox. A carrier passes the message along or drops it, often without any notice.

There is no spam folder to check. Carriers reject messages for several reasons:

  • The content looks like spam to the carrier’s filters.
  • The number is a landline or cannot receive texts.
  • The sender goes over the sending rate allowed for that number.

The cause usually sits outside your integration. Your code sees a normal status, so you need a check that watches for missed signers.

How do you catch a delivery failure in code?

Listen for the DeliveryFailed event from our webhook events. Our developer docs describe it as an email delivery failure for one or more recipients.

A second event, SendFailed, means the signature request itself failed to send. The two events point to different fixes, so give each one its own code path.

What does the DeliveryFailed payload contain?

Here is the DeliveryFailed sample payload for a failed email, as our docs show it:

{
    "event": {
        "id": "df150cce-7bc4-4b4d-97e2-ac0fdbdaffd4",
        "created": 1669980004,
        "eventType": "DeliveryFailed",
        "clientId": "ad174063-61cc-4f3f-8c83-f9e82dc4afe4",
        "environment": "Live"
    },
    "context": {
        "eventType": "DeliveryFailed",
        "actor": {
            "userType": "Signer",
            "id": "30e062d0-ae6a-4cc6-a78e-ae8cd232d8dd"
        },
        "previousState": {
            "failedDeliveryMode": "Email",
            "signerDetails": [
                {
                    "id": "30e062d0-ae6a-4cc6-a78e-ae8cd232d8dd",
                    "isDeliveryFailed": false
                }
            ]
        }
    },
    "data": {
        "object": "document",
        "documentId": "f46cc00e-c76f-4fb1-aa87-e5cfc0e0cfa7",
        "messageTitle": "API Test Document",
        "documentDescription": "This is document message sent from API",
        "status": "InProgress",
        "senderDetail": {
            "name": "Sender",
            "emailAddress": "sender@example.com",
            "userId": "3cb42cde-a514-4995-a83c-b423bb4bf163",
            "teamId": "bf4b33cd-239e-4940-b4ad-5b34bf987f7a"
        },
        "signerDetails": [
            {
                "signerName": "Signer",
                "signerRole": "",
                "signerEmail": "signer@example.com",
                "id": "30e062d0-ae6a-4cc6-a78e-ae8cd232d8dd",
                "status": "NotCompleted",
                "enableAccessCode": false,
                "isAuthenticationFailed": null,
                "enableEmailOTP": false,
                "isDeliveryFailed": true,
                "isViewed": false,
                "order": 1,
                "signerType": "Signer",
                "isReassigned": false,
                "reassignMessage": null,
                "declineMessage": null
            }
        ],
        "ccDetails": [],
        "onBehalfOf": null,
        "createdDate": 1669979993,
        "expiryDate": 1671301799,
        "enableSigningOrder": false,
        "disableEmails": false,
        "revokeMessage": null,
        "errorMessage": null,
        "labels": [
            "documentLabel"
        ],
        "brandId": "d6cfd0ce-b98d-4026-9f36-a40f91c8f2c8",
        "documentDownloadOption": "Combined",
        "metaData": {
            "documentType": "NDA",
            "documentCategory": "Legal"
        },
        "failedDeliveryMode": "Email"
    }
}

Two fields tell you what went wrong. The failedDeliveryMode field names the channel that failed, here Email. The isDeliveryFailed flag marks the signer who missed the message.

Can you check for failures without a webhook?

Yes, the same flag appears when you poll the document properties endpoint. Webhooks tell you sooner, so treat polling as a fallback.

What should your app do after a DeliveryFailed event?

Treat the event as a step in the workflow, not just an error log line. A quick response keeps a contract from sitting unsigned for days.

  1. Read failedDeliveryMode and find the signer whose isDeliveryFailed flag is true.
  2. Tell the document sender which signer missed the request.
  3. Ask the sender to check or correct that signer’s contact details.
  4. Send the request again once the address is fixed.

What should you watch out for?

The document status stays InProgress after a failed delivery. Code that checks only the status misses the failure.

Our docs describe DeliveryFailed for email, and the sample shows only the email channel. For text messages, watch for the Viewed event. Follow up through another channel when a signer still has not viewed the request after a day or two.

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

Webhooks and live API access come with the Enterprise API plan, from $30 a month with 40 envelopes included. Each extra envelope costs $0.75, as listed on the BoldSign pricing page in November 2026.

Prices are in USD.

You can build and test first in a free API sandbox, with no credit card needed. Sending by text message costs $0.20 per SMS on the Enterprise API plan.

In the web app, SMS delivery and a custom email domain start on the Business plan at $15 per user a month, billed yearly. The Premium plan, at $99 a month for unlimited users, includes them too.

How do you start testing delivery-failure events?

A simple way to learn the events is to send a test request to an address that does not exist. Then watch what reaches your endpoint.

Frequently asked questions

What is the difference between SendFailed and DeliveryFailed in BoldSign?

SendFailed means the signature request itself failed to send. DeliveryFailed comes later: we sent the request, but the email to a recipient did not arrive. Give each event its own code path, since the fixes differ.

What is a hard bounce and what should I do when one occurs?

A hard bounce is a permanent failure, such as an address that does not exist. Sending again to the same address will fail again. Correct the address first, then send the request again.

What is a soft bounce and is it worth retrying?

A soft bounce is a short-term failure, such as a full inbox or a busy mail server. Mail systems often try again for a while on their own. Wait a little, then check whether the signer has opened the request.

How does email authentication affect signature request delivery?

Receiving servers check sender records before they trust a message. A missing or wrong record can send the request to spam. The sender may get no bounce at all, so the problem can stay hidden.

Why might an SMS-based signature request fail to deliver?

Phone carriers filter text messages before they reach a phone. A carrier may drop a message that looks like spam, or one sent to a landline. Carriers rarely send back a notice like an email bounce.

Can I detect a delivery failure without using webhooks?

Yes. You can poll the document properties endpoint and read the isDeliveryFailed flag for each signer. Webhooks tell you sooner, so use polling as a fallback when you cannot accept incoming calls.

Which bulk electronic signature platforms handle failed deliveries and signer exceptions well?

Look for a platform that reports each failed delivery per signer, by event, in close to real time. In BoldSign, webhook events cover failed delivery, decline, reassignment and expiry, each with the document and signer details.

Does a delivery failure change the document status in BoldSign?

No, the status stays InProgress after a failed delivery. Only the signer record changes, with isDeliveryFailed set to true. Your code has to read that flag or listen for the event to notice.

BoldSign Team

The official team behind BoldSign—the simple, secure eSignature solution trusted by businesses worldwide. Our platform helps individuals and teams create, sign, and manage documents effortlessly while maintaining full compliance. Experience BoldSign yourself with a free trial or request a personalized demo to see it in action.

More posts by BoldSign Team
Get started

Sign up for your free trial today!

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