Troubleshooting
Recipient didn't get the signing email
Find out why a recipient didn't receive the signing request email, from test mode and routing order to bounces and blocked addresses, and how to fix each case.
A recipient says the signing request never arrived. Work through the causes below in order: the first ones are the most common, and each one shows up in the recipient’s status or in an event.
Start by reading the recipient with Get a recipient, or open the envelope in the Dashboard, and note the recipient’s status.
Recipient status | What it means | Go to |
|---|---|---|
awaiting | An earlier recipient hasn’t finished yet. | Sequential routing |
pending | No request has been sent yet. | Ceremony not sent |
sent | SignatureAPI sent the email. | Sent but not received |
soft_bounced | The mail server refused it for now. | Soft bounce |
hard_bounced | The address doesn’t accept mail. | Hard bounce |
failed | SignatureAPI couldn’t send it. | Blocked address |
The envelope is in test mode
Envelopes created with a test API key never send email to recipients. That’s by design, so you can test without reaching real inboxes. You can read every test email in the Dashboard under Emails with Test Mode on.
To send real emails, create the envelope with a live API key. See Test mode.
The recipient is waiting for their turn
With sequential routing, the default, recipients act one at a time in the order of the recipients array. Later recipients stay awaiting and get their email only when everyone before them has finished. Check who’s next in the envelope, and remind that person instead.
If every recipient should get the email at once, create the envelope with "routing": "parallel". Parallel routing accepts signers and automatic signers only.
The recipient is pending
A pending recipient hasn’t been sent anything yet. Two common reasons:
- The envelope is still
processing. SignatureAPI sends the requests once the envelope moves toin_progress. If it moved tofailedinstead, read thedetailof theenvelope.failedevent. - You create the ceremony yourself. A recipient whose ceremony you create, such as a replacement recipient, stays
pendinguntil you call Create a ceremony.
The ceremony doesn’t use email
SignatureAPI sends the signing request email only when the recipient’s ceremony uses email_link authentication. With another method, such as an email code or your own custom authentication, SignatureAPI sends no invitation: you deliver the ceremony URL yourself, for example inside your app.
The email was sent but the recipient can’t find it
sent means SignatureAPI handed the email to the mail system. It doesn’t mean it reached the inbox. Check these, in order:
- The address. Look for a typo in the recipient’s
email. A mistyped address that exists somewhere else delivers fine, to the wrong person. - The delivery report. Open the email in the Dashboard under Emails. Delivered means the recipient’s mail server accepted it, and the SMTP response shows its exact answer. See Emails.
- Spam and other folders. Ask the recipient to search all folders, including spam, junk and promotions, for the envelope title or the sender’s name.
- Company filters. Corporate mail systems sometimes hold or quarantine messages from outside senders without telling the recipient. Ask their IT team to release it and to allow messages from SignatureAPI.
The email names the envelope’s sender, and replies go to the sender’s address. A sender the recipient recognizes is less likely to be ignored or flagged. To send from your own domain, see Branding add-ons.
When the email is found or released, nothing else is needed. If it’s gone, resend the request.
The email soft bounced
A soft bounce is a temporary refusal, such as a full mailbox or a server that’s briefly unavailable. The recipient’s status becomes soft_bounced, and the recipient.soft_bounced event carries the mail server’s reason in data.detail. Wait a while, or ask the recipient to free up space, then resend the request.
The email hard bounced
A hard bounce is a permanent refusal: usually the address doesn’t exist or the domain doesn’t accept mail. The recipient’s status becomes hard_bounced, and the recipient.hard_bounced event carries the reason in data.detail. The SMTP response is in the Dashboard under Emails.
You can’t resend to a hard-bounced recipient. Confirm the right address with the person, then replace the recipient with the corrected one.
The address is blocked
After a hard bounce, or after the recipient marks an email from SignatureAPI as spam, the address goes on a blocklist. A new envelope or recipient with that address fails with blocked-email, and a recipient whose address became blocked moves to failed with the reason in the recipient.failed event.
Check the address for typos first. If it’s correct and the mailbox works again, contact support to have it unblocked, or replace the recipient with a different address.
Resend the request
Resend request sends the email again. It works when the ceremony uses email_link authentication, the recipient is sent or soft_bounced, and the envelope is in_progress. Read can_resend_at from each response: resends are spaced out, and a recipient gets at most 10 emails.
Track delivery automatically
Subscribe your webhook endpoint to recipient.sent, recipient.soft_bounced, recipient.hard_bounced and recipient.failed. Then your app can tell the sender right away, instead of waiting for a recipient to say they never got anything.
Related
- Recipient lifecycle: every status and the event it emits.
- Recipient events: payloads for each event.
- Troubleshooting embedded signing: when you show the ceremony in your app.