How to Detect Email and SMS Delivery Failure in eSignature Code

TL;DR: A signature request that never gets signed is not always a signer problem. In some cases, it is a delivery problem: a hard or soft email bounce, a missing SPF or DKIM record that pushed the message to spam, or an SMS blocked by a carrier before it ever reached a phone.

Most email bounces, spam filtering decisions, and SMS carrier rejections are invisible from inside your application unless you’re specifically watching for it, which is exactly what a delivery-failure webhook is for.

A signer never opens the signature request. Days later, the sender checks the document status and still sees it marked as in progress, with no error, no bounce notice, and nothing obviously wrong. The document was sent successfully. It just never arrived.

That gap, between “sent” and “actually delivered,” is where most eSignature completion problems quietly live. Email bounces, spam filters, and SMS carrier rejections all happen after your API call succeeds, which is exactly why they’re easy to miss.

None of this is eSignature-specific. It’s the same email and SMS infrastructure every notification-sending application depends on, with the same failure modes: hard bounces, soft bounces, authentication records that decide whether a message looks legitimate, and carriers that block unregistered senders outright.

What’s different is what you can actually do about it in code, and that’s where this gets specific.

The practical solution is to monitor delivery-failure events and respond to them in code before documents stall indefinitely.

For businesses, a delivery problem can look like signer inactivity. That can delay contract approvals, onboarding workflows, vendor agreements, or compliance documentation, even when the signer was ready to act.

Here’s how that gap actually shows up in BoldSign, and the mechanism that lets your code catch it instead of guessing.

Key takeaways

• A signature request “sent” successfully by the API and one actually delivered to a recipient’s inbox or phone are two different things, and the gap between them is where most silent failures happen.
• Email bounces come in two kinds: hard bounces (permanent, like an invalid address, SMTP 5xx) and soft bounces (temporary, like a full inbox, SMTP 4xx).
• SPF, DKIM, and DMARC don’t stop a message from sending. They decide whether the receiving server trusts it enough to deliver it to an inbox instead of spam or nowhere at all.
• SMS fails through a different mechanism entirely, carrier-level filtering and registration requirements rather than inbox rules, and it can be blocked outright with no bounce-like notice at all.

BoldSign exposes a DeliveryFailed webhook event specifically for this, separate from SendFailed, so your code can react to a failed delivery instead of a signer just never mentioning it.

“Sent” and “delivered” are not the same status

Email bounces fall into two categories, and the difference changes what you should do about each one. A hard bounce is permanent: the address doesn’t exist, the domain is gone, or the mailbox was deleted. Retrying does nothing. The message needs a different destination entirely.

A soft bounce is temporary: a full inbox, a receiving server that’s briefly down, a message that’s momentarily too large. Most email systems, including Amazon SES, retry temporary delivery failures for a period before ultimately stopping delivery attempts if the issue persists.

This maps onto SMTP status codes where a system exposes them: codes in the 4xx range are soft, temporary failures, and codes in the 5xx range are hard, permanent ones. Not every provider surfaces the raw code, but the 4xx and 5xx distinction is the one worth remembering.

For a signature request specifically, the practical difference is what you tell the sender. A hard bounce means the email address is wrong and needs correcting before anything else works. A soft bounce means the request is probably still coming through, just later than expected.

SPF, DKIM, and DMARC decide whether the message is trusted before it lands anywhere

A message can leave a sending server successfully and still never reach an inbox because the receiving server performs authentication checks first. These checks rely on three email authentication mechanisms: SPF, DKIM, and DMARC.

SPF lists which mail servers are allowed to send on behalf of a domain. This information is published through the domain’s DNS settings.

DKIM adds a digital signature to each outgoing message. This allows the receiving server to confirm the message wasn’t altered in transit and actually came from that domain.

DMARC sits on top of both SPF and DKIM. It checks whether the authenticated domain matches the domain shown in the From address. It also tells receiving servers how to handle failures, such as delivering the message, sending it to spam, or rejecting it.

A missing or misconfigured record doesn’t always produce a bounce you’d notice. Depending on the receiving provider’s policy, the message can land quietly in spam with no notification to either side, which is arguably worse than a bounce, since nothing tells you to go fix it.

When you configure a custom sending domain for your own domain, BoldSign provides the required DNS configuration details, such as DKIM and Return-Path records, through a support-ticket-based verification process. This applies specifically when using a custom sending domain rather than the default BoldSign sending domain. Verification happens through a support ticket rather than an automated check, so it’s a step to plan for, not something that completes the moment you save the settings.

SMS fails through carriers, not inboxes

SMS delivery breaks differently, and the failures are often more silent than email. There’s no inbox to land in and no spam folder to check. A carrier either passes the message along or it doesn’t, and the reasons are largely outside your application entirely.

In the US, carrier registration requirements for application-to-person (A2P) messaging, specifically 10DLC registration for long codes, can prevent some application messages from being delivered if the sending setup is not compliant. Requirements vary by country; other regions have their own frameworks, but the same principle applies: unregistered senders can be silently blocked.

Beyond registration, carriers reject messages for content that trips spam filters, numbers that are landlines or otherwise can’t receive SMS, and sending rates that exceed what a number is approved for. Each system involved in routing the message between sender and recipient is another point where delivery can fail.

If you’re sending signature requests by SMS, this is worth knowing before a signer says they never got a text: the failure usually isn’t your integration, and it usually won’t look like an error unless something downstream is specifically watching for it.

Catching the failure in code

This is the part that actually matters for your integration: does anything tell your application when a signature request failed to reach someone? For BoldSign, the answer is a specific webhook event, separate from the one that fires when a send request fails outright.

SendFailed fires when the API request itself couldn’t be processed, like a template reference that doesn’t resolve. DeliveryFailed fires afterward, once the request was accepted and sent, but a recipient’s email notification didn’t get through. They’re solving different problems and shouldn’t be handled by the same code path.

Here is an example DeliveryFailed event payload for email delivery, as BoldSign documents 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": "[email protected]",
            "userId": "3cb42cde-a514-4995-a83c-b423bb4bf163",
            "teamId": "bf4b33cd-239e-4940-b4ad-5b34bf987f7a"
        },
        "signerDetails": [
            {
                "signerName": "Signer",
                "signerRole": "",
                "signerEmail": "[email protected]",
                "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"
    }
}
            

The event identifies the failed delivery channel through failedDeliveryMode. It also identifies the affected recipient through the isDeliveryFailed flag on the signer’s record. That same flag is also visible if you poll a document’s status directly, so a webhook isn’t the only way to catch it, just the fastest.

BoldSign provides the delivery-failure signal through its DeliveryFailed webhook event and document status API, helping teams identify delivery issues before documents sit unsigned for days. Your application can then decide how to respond, such as notifying the sender, correcting an invalid address, or triggering a manual follow-up.

Treat delivery failures as workflow events

A delivery failure doesn’t look like an error. The API call succeeded, the document status still says in progress, and nothing crashes. Meanwhile a contract renewal or an onboarding form sits unsigned, not because anyone is stalling, but because the request never reached anyone to stall on. That’s exactly why it needs its own handling instead of getting lumped in with generic error checking.

If you’re sending signature requests at any real volume, treat DeliveryFailed as a workflow event, not just a notification issue. The cost of catching it late isn’t abstract, it’s a deal or a deadline sitting on someone’s desk with no visible reason why.

If you’d like to test how delivery-failure events behave in practice, you can use a BoldSign sandbox account to observe webhook events and document status updates.

FAQs