# Status Reporting

Status reporting allows integrators to monitor delivery processing and determine whether submitted messages have been successfully delivered to receivers.

All delivery outcomes are reported through the Delivery API and must be used as the authoritative source for operational status.

This section explains how delivery status works, when to request status information, and how to interpret delivery results.

## Overview

Each delivery submitted to the platform is processed asynchronously.

After submission:

- Validation is performed
- Content is ingested
- Recipients are resolved
- Messages are prepared
- Delivery is completed


During this process, status information becomes available through the Delivery API.

Integrators must poll for status until processing is complete.

## Delivery Level Status

Each delivery has an overall status.

| Status | Description |
|  --- | --- |
| Processing | Envelopes are being validated and delivered |
| Completed | All envelopes have been processed |


The delivery status reflects the overall processing state.

`Completed` does not mean all envelopes succeeded. It means processing has finished.

Individual envelope results must be inspected for detailed outcomes.

The delivery report also includes:

- `totalEnvelopes` — the total number of envelopes in the delivery
- `deliveredEnvelopes` — the number of envelopes successfully delivered


While `status` is `Processing`, `totalEnvelopes` may still increase as envelopes are discovered.

## Envelope Level Results

Envelope outcomes are reported in the `logs` array of the delivery report.

Successfully delivered envelopes are **not** listed in `logs`. Successful delivery is determined by comparing `deliveredEnvelopes` to `totalEnvelopes` when the delivery status is `Completed`.

Failed or problematic envelopes appear as entries in the `logs` array. Each log entry contains:

| Field | Description |
|  --- | --- |
| `envelopeId` | The message ID of the envelope this entry relates to. Optional if the entry applies to the delivery as a whole. |
| `delivered` | Whether the envelope was delivered. Optional if the entry applies to the delivery as a whole. |
| `level` | The significance of the entry: `Warning` or `Error`. |
| `key` | A key identifying the failure or event type. |
| `description` | A human-readable explanation of the issue. |


Important behavior:

- There may be multiple log entries for the same `envelopeId`
- If `delivered` is `false`, the envelope failed
- If `delivered` is omitted, the entry applies to the delivery as a whole
- Warnings may appear for successfully delivered envelopes (e.g. deprecated features)


Envelope results are only final when the delivery status is `Completed`.

## When to Request Status

Status should not be queried immediately after creating a delivery.

The first status check should occur no earlier than **15 minutes** after submission.

Recommended approach:

1. Submit delivery
2. Wait at least 15 minutes
3. Request delivery report
4. If status is `Processing`, wait and poll again
5. Repeat until status is `Completed`


Typical polling pattern:

- Initial wait: 15 minutes
- Poll interval: 5 to 15 minutes
- Continue until `Completed`


Excessive polling should be avoided.

## Retrieving Delivery Status

Status information is retrieved using the Delivery API endpoint `GET /delivery/v1/deliveries/{deliveryId}` ([Get delivery report](/apis/delivery/delivery/other/getdeliveryreport)).

Example:

```http
GET /delivery/v1/deliveries/{deliveryId}
Authorization: Bearer <access-token>
```

The response contains:

- Delivery status (`Processing` or `Completed`)
- Envelope counts (`totalEnvelopes`, `deliveredEnvelopes`)
- Log entries for failed or notable envelopes
- Delivery creation timestamp


Refer to the [Delivery API reference](/apis/delivery/delivery/other/getdeliveryreport) for the full response schema.

## Interpreting Delivery Reports

Delivery reports provide detailed diagnostics.

A report includes:

- Overall delivery status and envelope counts
- Log entries describing failures and warnings per envelope
- Failure keys that categorize each issue


To determine delivery success:

1. Check that `status` is `Completed`
2. Compare `deliveredEnvelopes` to `totalEnvelopes`
3. Inspect `logs` for details on any failures


Delivery reports should be archived for audit and support purposes.

## Common Failure Categories

Failures are reported in the `logs` array and categorized by the `key` field.

| Category | Common keys | Typical handling |
|  --- | --- | --- |
| Envelope validation | `InvalidEnvelope` | Fix envelope data or schema and resubmit. |
| Content missing or invalid | `EnvelopeContentMissing`, `EnvelopeContentMediaTypeNotAuthorized`, `EnvelopeContentFileExtensionsNotAuthorized` | Fix S3 objects and resubmit. |
| Recipient resolution | `RecipientNotFound`, `RecipientNotSubscribed` | Fix recipient data or subscriptions and resubmit. |
| Sender authorization | `SenderNotFound`, `SenderNotAuthorized` | Verify sender configuration and permissions. |
| Delivery conflicts | `EnvelopeAlreadyDelivered`, `EnvelopeAlreadyDeliveredWithOtherDelivery`, `EnvelopeBeingProcessedInOtherDelivery` | Verify idempotency and messageId usage. |
| Security scanning | `VirusDetected` | Replace content and resubmit. |
| S3 access and transfer | `S3AccessDenied`, `UnabletoConnectAmazonS3`, `S3CopyFailed`, `NotFound` | Verify S3 credentials, access, and object presence. |
| Encryption | `InvalidEncryptionMarker`, `CouldNotBeDecrypted`, `InvalidEncryptionKeyEncoding`, `CouldNotReadInitializationVector` | Verify encryption key and encoding. |
| Content integrity | `InvalidHash` | Verify file content matches the hash in the envelope. |
| Content size or type | `ToLarge`, `UnauthorizedMediaType` | Reduce file size or use an allowed media type. |
| Signing and registration | `UnableToRegisterSigningRequest` | Retry later or contact support. |
| Platform or processing | `DeliveryFault` | Retry later; contact support if persistent. |
| Delivery discovery | `NoEnvelopesFound` | Verify S3 prefixes and envelope presence. |


Failure reasons are included in the `description` field of each log entry.

## Platform Retry Behavior

If delivery fails due to temporary conditions, the platform automatically retries processing.

Retries may continue for up to one hour.

During this period:

- `status` remains `Processing`
- `logs` entries may change
- `deliveredEnvelopes` may increase


After the retry window expires:

- `status` transitions to `Completed`
- Failed envelopes remain in `logs`


Do not resubmit while the delivery is still `Processing`.

## Handling Permanent Failures

Some failures require correction before resubmission.

Examples:

- Invalid envelope schema
- Missing recipient identity
- Unauthorized sender
- Virus detected in content


For permanent failures:

1. Retrieve the delivery report
2. Identify failed envelopes from `logs`
3. Analyze the `key` and `description` for each failure
4. Correct the root cause
5. Resubmit the corrected envelopes in a new delivery


## Handling Temporary Failures

Some failures may be temporary.

Examples:

- Network interruptions
- Temporary storage issues
- Downstream service unavailability


For temporary failures:

- Implement exponential backoff
- Limit retry attempts
- Monitor failure patterns
- Escalate persistent issues


## Monitoring Best Practices

Recommended monitoring practices include:

- Track delivery success rates
- Monitor failure categories by `key`
- Alert on abnormal failure spikes
- Log `deliveryId`,`EnvelopeId`, envelope counts, and log entries
- Retain delivery reports for audit


Integrators should implement centralized monitoring where possible.

## Timeouts and Long Running Deliveries

Large deliveries may require extended processing time.

Factors affecting processing time include:

- File size
- Number of envelopes
- Recipient volume
- Encryption settings


For long running deliveries:

- Increase polling intervals
- Avoid premature failure assumptions
- Monitor platform maintenance notices


## Relationship to Other Sections

Status reporting is closely related to:

- [Verify and Troubleshoot](/getting-started/verify-delivery)
- [Message Delivery Model](/documentation/delivery-model)
- [Delivery API Reference](/apis/delivery/delivery/other/getdeliveryreport)


Understanding delivery processing is required for correct interpretation of status data.

## Next Steps

After implementing status monitoring, continue with:

- Recipient Identification
- Error Handling Guidelines
- Performance Optimization
- Security Concepts