# EviPost

EviPost is the Namirial Notify service for sending certified physical postal communications. You submit a document online; a postal provider prints it and delivers it to the recipient's postal address. The platform records the postal events reported by the provider and generates signed affidavits according to the selected configuration.

Its purpose is comparable to services such as a burofax in Spain or a *raccomandata con ricevuta di ritorno* in Italy. **EviPost is currently available only for delivery within Spain.** Delivery options and evidence depend on the selected EviPost service type and configuration.

This page explains EviPost behaviour and includes guidance for API integrators. To send from the Web app, follow [How to create a new EviPost](/products/namirialnotify/issuer/create-evipost). For request and response definitions, see the [EviPost API reference](/products/namirialnotify/apis/evipost-api).

## When to use EviPost

Use EviPost when:

- **Physical delivery is required or preferred** — the recipient must receive a printed, sealed document at their postal address.
- **You need evidence of physical delivery** — the postal operator reports delivery outcomes that can be certified in affidavits.
- **Digital delivery does not meet your requirements** — your process requires a physical postal communication.


Use [EviMail](/products/namirialnotify/services/evimail) when certified delivery via email is sufficient. Use [EviNotice](/products/namirialnotify/services/evinotice) when you need a hosted digital notice with proof of delivery, recipient authentication, or acceptance/rejection workflows. EviNotice distinguishes delivery of the notification from access to and reading of the hosted content; the available evidence depends on the channel and configuration. Use [EviSMS](/products/namirialnotify/services/evisms) for certified mobile delivery.

**Postal delivery times**

EviPost operates on postal timelines: delivery and tracking updates can take days or weeks. Sending the document starts postal processing; it does not confirm delivery.

## How EviPost works

### Lifecycle overview


```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#E4F2F2', 'primaryBorderColor': '#006660', 'primaryTextColor': '#0A1111', 'lineColor': '#047C76', 'secondaryColor': '#CDDBDB', 'tertiaryColor': '#f5fafa', 'edgeLabelBackground': '#f5fafa', 'transitionColor': '#047C76'}}}%%
stateDiagram-v2
    [*] --> Submitted : Submit accepted
    Submitted --> Processed : Document validated and certified
    Submitted --> Closed : Invalid document (Failed)
    Processed --> Dispatched : Postal operator acknowledged
    Dispatched --> Issued : Item issued by provider
    Issued --> Sent : Item sent
    Dispatched --> Sent : Item sent (direct)
    Sent --> Delivered : Delivery reported
    Sent --> Undelivered : Non-delivery reported
    Sent --> Closed : Plain Letter (Sent) or Registered (Rejected)
    Undelivered --> Disposed : Letter configured for disposal
    Undelivered --> Failed : Letter with a later failure report
    Undelivered --> Closed : Registered or LetterLite final non-delivery
    Sent --> Failed : Processing or delivery failure
    Delivered --> Closed : Final delivery result
    Disposed --> Closed : Final disposal result
    Failed --> Closed : Final failure result
    Dispatched --> Cancelled : Tracked Letter cancellation confirmed
    Cancelled --> Closed : Final cancellation result

    note right of Sent
        Paths depend on the service type and reported events.
        A failed delivery attempt is an event, not Undelivered.
        Use the outcome at Closed as the final result.
    end note
```

### Key state transitions

These are common paths. The selected service type, configuration, and the events reported by the postal operator determine which steps appear.

**Submitted → Processed** — Namirial Notify validates the document (PDF format and page count), certifies it, and dispatches a send request to the postal operator. If the document is invalid or the page count exceeds the subscribed tier, the communication closes immediately as `Failed`.

**Processed → Dispatched** — The postal operator acknowledged receipt of the item.

**Dispatched → Issued** — The courier collected the item for physical delivery. `Issued` is an operator-reported intermediate state; not all operators or service configurations report it.

**Issued / Dispatched → Sent** — The item is in transit with the postal operator or courier.

**Sent → Delivered** — The item was successfully delivered to the recipient. For registered post, this requires the recipient to sign for delivery.

**Sent → Undelivered** — The postal operator reported non-delivery. This is distinct from an individual failed delivery attempt and does not by itself close the communication. Read the event history for the reason and wait for `Closed` to interpret the final outcome. See [Delivery attempts and non-delivery](#delivery-attempts-and-non-delivery).

**Undelivered → Disposed** — For a `Letter` service configured for disposal, the provider reported destruction of the undelivered item. This step does not apply to every service type and is separate from online evidence retention.

**Dispatched → Cancelled** — Cancellation was confirmed for a `Letter` with delivery tracking enabled. Requests are subject to the configured cancellation window (30 minutes from creation by default) and confirmation by the postal operator.

### Delivery attempts and non-delivery

A **state** describes the current phase, an **event** records something that happened, and an **outcome** records the result. An outcome can change while the communication remains open; use the outcome at `Closed` as the final result.

| What happened | How to interpret it |
|  --- | --- |
| An individual delivery attempt failed | A delivery-attempt event records the attempt. It does not by itself change the state to `Undelivered` or close the communication. Further attempts depend on the service type, configuration, and operator. |
| The operator reported `Undelivered` | Non-delivery has been recorded, but the communication is still open until `Closed`. For `Registered` and `Letter` with delivery tracking enabled, the platform accepts a later valid delivery report before closure. This is not a confirmed operator sequence or a promise of redelivery. `LetterLite` cannot complete normal closure with `Delivered` once non-delivery has been recorded. |
| A final non-delivery result was received | `Registered` and `LetterLite` can close with outcome `Undelivered`. For a `Letter` service configured for disposal, the workflow can continue to `Disposed` before closure. A later failure report for `Letter` can instead lead to `Failed` and closure with that outcome. |
| The item is awaiting collection or being returned | Do not infer this from `Undelivered` alone. There is no dedicated collection or return-to-sender state in the EviPost API contract. Check the operator details in the event history or available affidavits; contact support if the next postal action is unclear. |


Once the communication is `Closed`, later postal progress reports do not reopen its lifecycle. Affidavits may still become available afterwards.

**For integrators receiving callbacks.** `Undelivered` and delivery-attempt events are not selectable EviPost push filters. Subscribe to `Closed` for the final `AdditionalData.Outcome`, and use Query to reconcile the current state and outcome. See [Callbacks and what you receive](#callbacks-and-what-you-receive).

## Send an EviPost from the Web app

Have the PDF, the recipient's name and Spanish postal address, and the issuer's name and postal address ready. The issuer's region is required. The recipient's region is also required when you select **Certified delivery** (`Registered`). Account settings can supply some values in advance.

1. Open **New EviPost** in the issuer area.
2. In **Content**, enter the recipient details and attach the PDF.
3. In **Issuer**, review or complete the sender details.
4. In **Advanced**, review the type of service under **Profile service**, then the certification and custody settings.
5. Open **Preview**, check the document and addresses, then click **Send**.


Follow [How to create a new EviPost](/products/namirialnotify/issuer/create-evipost) for the required-field checklist, screenshots of the form, and detailed instructions. After sending, use [EviPost transaction search](/products/namirialnotify/issuer/transactions-search-evipost) to follow its progress and open the available evidence.

## Submit a certified postal communication

**For API integrators.** This section describes the Submit request. Web app users can follow the [issuer guide](/products/namirialnotify/issuer/create-evipost).

**Allow for postal processing time**

Process status updates asynchronously as postal events arrive. A successful Submit response confirms acceptance by the platform, not physical delivery. Use callbacks and Query reconciliation instead of waiting for delivery in the submission request.


```
POST /v1/EviPost/Submit
```

Returns `{ "uniqueId": "..." }` on success. Note that `uniqueId` is camelCase, consistent with the other v1 services — the equivalent field in EviMail and EviSMS is named `eviId`.

### Required fields

| Field | Description |
|  --- | --- |
| `Document` | The letter or document to be sent, base64-encoded PDF. |
| `RecipientAddress` | Physical delivery address. See [Address fields](#address-fields). |


### Optional fields

- **`RecipientName`** — display name of the recipient.
- **`RecipientLegalName`** — legal name of the recipient, recorded in the certification evidence.
- **`IssuerName`** — display name of the sender.
- **`IssuerLegalName`** — legal name of the sender, recorded in the evidence.
- **`IssuerAddress`** — return address for the sender. See [Address fields](#address-fields).
- **`Options`** — processing and certification settings. When omitted, platform defaults apply. See [Options](#options).
- **`LookupKey`** — your own correlation key, filterable in Query.
- **`RecipientPhone`** — recipient's mobile number.
- **`RecipientEmail`** — recipient's email address.
- **`IssuerPhone`** — sender's phone number.
- **`IssuerEmail`** — sender's email address.
- **`IssuerComments`** — additional comments from the sender, included in the evidence.


### Address fields

Both `RecipientAddress` and `IssuerAddress` use the same structure:

| Field | Required | Description |
|  --- | --- | --- |
| `StreetAddress` | Yes | Street name and number. |
| `PostalCode` | Yes | Postal code. |
| `Locality` | Yes | City or town. |
| `Country` | Yes | ISO 3166-1 alpha-2 country code (e.g. `ES`). |
| `Region` | Conditional | Province or region. Required in `RecipientAddress` for `Registered`. The issuer region must also be present, either supplied in `IssuerAddress` or filled from the site address. |
| `PostOfficeBoxAddress` | No | Post office box address, if applicable. |


### Options

All processing and certification configuration lives inside the `Options` object.

Every field in `Options` is optional at the API level. When you omit one, the platform applies a default (noted per field below) — for example `PostServiceType` becomes `Registered`, `Language` follows your site's configured language, `AffidavitProfile` is inferred from `CertificationLevel`, and `EvidenceAccessControlMethod` follows the account's configured default method. The Web form preselects its own account or site defaults; these need not match the API defaults. In particular, the Web service type comes from the site configuration. The few genuinely conditional requirements — `PostServiceProfile` for `Letter`, and the challenge fields for the `Challenge` access method — are called out below.

- **`PostServiceType`** — `Registered` (default), `Letter`, or `LetterLite`. If omitted, defaults to `Registered`. See [Service types](#service-types) below.
- **`PostServiceProfile`** — identifier of the postal-service profile to use. **Required when `PostServiceType` is `Letter`** (the profile selects the printing/logistics variant and must be provisioned for your account beforehand). Not used for `Registered` or `LetterLite`.
- **`CertificationLevel`** — the legal framework applied. Supported values include `Standard`, `Advanced`, and regional variants such as `Standard_EU` or `Advanced_EU`. Availability depends on the account. EviPost does not support QERDS certification levels.
- **`AffidavitProfile`** — controls which affidavits are generated. If omitted, it is inferred from `CertificationLevel`; if you set it explicitly, it must be consistent with the certification level. See [Affidavit profiles](#affidavit-profiles) below.
- **`AffidavitsOnDemandEnabled`** — set `true` at submit time to allow on-demand affidavit generation later via `POST /v1/EviPost/AffidavitRequest`. Requires an advanced `AffidavitProfile` (`AdvancedContentOnSubmit`, `AdvancedContentOnClose`, or `AdvancedContentOnSubmitAndOnClose`). **Cannot be enabled retroactively.**
- **`OnlineRetentionPeriod`** — years the communication and its evidence remain accessible online. Default: 1 year.
- **`NotaryRetentionPeriod`** — years of notarial custody. Set to `5` to apply notarial retention; set to `0` to disable. Requires `NotaryProfile` when greater than 0.
- **`NotaryProfile`** — identifier of the notary for custody. Required when `NotaryRetentionPeriod > 0`.
- **`EvidenceAccessControlMethod`** — controls how the evidence record is accessed: `Public`, `Challenge`, `AutoChallenge` (the account's configured default method applies when omitted). When set to `Challenge`, you must also supply `EvidenceAccessControlChallenge` and `EvidenceAccessControlChallengeResponse`.
- **`EvidenceAccessControlChallenge`** / **`EvidenceAccessControlChallengeResponse`** — the challenge question and its expected answer. Both are required when `EvidenceAccessControlMethod` is `Challenge`.
- **`Language`** — language for the evidence record and affidavit documents. If omitted, defaults to your site's configured language.
- **`PushNotificationUrl`** — HTTPS endpoint to receive state callbacks. Optional; if you set it, also set `PushNotificationFilter` — without a filter, no events are sent.
- **`PushNotificationFilter`** — state transitions that trigger a callback. Valid values: `Processed`, `Dispatched`, `Sent`, `Delivered`, `Closed`, `Cancelled`, `Issued`, `Disposed`, `AffidavitPublished`. `AffidavitPublished` is a platform meta-event that fires when affidavit generation completes — it is not a lifecycle state.
- **`PushNotificationExtraData`** — arbitrary string echoed back in every callback.
- **`CostCentre`** — optional billing group identifier.
- **`CustomFields`** — array of custom key-value fields attached to the submission. Fields with `IsLookupKey: true` are indexed and returned in query results under `LookupKey`.


### Idempotency

Include `X-Evi-IdempotencyToken` on every Submit. Use a UUID and keep it constant across retries. A replay of a `200 OK` submission returns `202 Accepted`; the communication is not resubmitted.

## Service types

EviPost physical delivery is currently available for destinations within **Spain**. Senders located outside Spain can use EviPost to deliver to Spanish addresses. Availability of each service type and `PostServiceProfile` depends on your account provisioning.

### Registered (API default) 

Sends a certified postal communication through the national postal operator (Correos). The operator tracks the item through the postal chain and reports delivery outcomes. Suitable when you need maximum tracking and evidence coverage. This is the default for API submissions that omit `PostServiceType`. The Web app preselects the service type configured for the site. See the [Web service-name mapping](/products/namirialnotify/issuer/create-evipost#review-options).

Delivery attempts for `Registered` are handled by the postal operator and are not configured through the submit request — the delivery-attempt and disposal options below apply to `Letter` only.

### Letter

Sends the document to a printing and enveloping provider (MRW) for certified delivery. Requires prior provisioning by your Namirial Notify contact, and a `PostServiceProfile` must be supplied. Supports optional delivery receipt and delivery attempt tracking:

- **`EnableDeliveryReceipt`** — request a signed delivery receipt from the provider.
- **`EnableDeliveryAttempts`** — enable delivery attempt tracking.
- **`DeliveryAttemptsNumber`** — number of delivery attempts before the process ends.
- **`DisposalDaysAmmount`** — days after which the item is disposed of if undelivered. Note: the field name contains a typo (`Ammount`) that matches the API contract.
- **`PostServiceProfile`** — profile identifier for the printing and enveloping provider. Required for `Letter`, and must be provisioned before use.


### Letter Lite

A lower-cost printed certified letter (`LetterLite`), delivered through MRW. It is a single-attempt service with the following constraints, enforced at submit time:

- Available **only for destinations within mainland Spain** — the Spanish islands, Ceuta, Melilla, Portugal, Andorra, and Gibraltar are excluded.
- A single delivery attempt — the delivery-attempt options (`EnableDeliveryAttempts`, `DeliveryAttemptsNumber`) cannot be used.
- No disposal step — `DisposalDaysAmmount` cannot be used.
- `PostServiceProfile` is not required.


## Affidavit profiles

`AffidavitProfile` in `Options` controls which affidavits are generated:

| Value | Description |
|  --- | --- |
| `None` | No affidavits generated. |
| `Basic` | A single receipt affidavit when tracking is complete. Default for `Standard` certification. |
| `AdvancedContentOnSubmit` | One affidavit per event, plus a timestamped content affidavit at submission. Default for `Advanced` certification. |
| `AdvancedContentOnClose` | One affidavit per event, plus a receipt showing the document body when tracking is complete. |
| `AdvancedContentOnSubmitAndOnClose` | Combination of the above two. |


To enable on-demand affidavit generation via `POST /v1/EviPost/AffidavitRequest`, set `AffidavitsOnDemandEnabled: true` and use an Advanced profile. This cannot be enabled retroactively.

## Callbacks and what you receive

**For integrators receiving callbacks.** A callback is an HTTP notification sent to your application. It can be configured during API submission or in the Web form's **Advanced** tab. Users who only track communications in the Web app do not need a callback endpoint.

When a state in `PushNotificationFilter` is reached, Namirial Notify sends an HTTP POST to `PushNotificationUrl`.

### Base payload

| Field | Type | Description |
|  --- | --- | --- |
| `Identifier` | string | ID of this callback, retained across retries. Use it to detect repeated deliveries of the same callback. |
| `Kind` | string | The state or event that triggered this callback (e.g. `Dispatched`, `Sent`, `Delivered`, `Closed`). |
| `Date` | datetime | Timestamp of the event. |
| `EvidenceId` | UUID | The `UniqueId` of the EviPost, as returned at submission. |
| `EvidenceType` | string | Always `eviPost` for EviPost callbacks. |
| `EvidenceState` | string/null | Not populated by this service. Accept an absent or null value and use `AdditionalData.State`. |
| `Site` | string | Name of the issuer's site. |
| `Owner` | string/null | Not populated by this service. Accept an absent or null value; do not require it. |
| `OwnerEmail` | string | Email address of the account owner. |
| `AdditionalData` | object | Common and event-specific fields described below. |


### `AdditionalData` fields — always present

| Field | Description |
|  --- | --- |
| `Sender` | Name of the sender (`IssuerName`). |
| `Recipient` | Name of the recipient (`RecipientName`). |
| `LookupKey` | The integrator-assigned lookup key set at submission. |
| `State` | Current lifecycle state. |
| `CreationDate` | Timestamp when the communication was submitted. |


### Optional correlation data

`AdditionalData.ExtraData` is included only when `PushNotificationExtraData` was supplied at submission. It contains the reference used to match the callback to your own records.

### `AdditionalData` fields — per event

| Callback `Kind` | Extra fields |
|  --- | --- |
| `Dispatched`, `Sent`, `Issued` | `TransmissionDetails` — postal operator transmission details for this event. |
| `Delivered` | `Details` — delivery details reported by the postal operator. |
| `Closed` | `Outcome` — the final outcome of the postal process. |
| `AffidavitPublished` | `AffidavitId`, `AffidavitName` — identifiers of the generated affidavit. `RequestId` — present when the affidavit was generated on demand. |


### Callback reliability

For your receiving application, follow [Handling callbacks reliably](/products/namirialnotify/dev/callbacks#handling-callbacks-reliably). It explains how to process retries only once using `Identifier`, acknowledge a callback after safely storing it, and match it to your own records using `AdditionalData.ExtraData`.

### Securing your callback endpoint

Use the shared [callback endpoint controls](/products/namirialnotify/dev/security-best-practices#callback-endpoint-hardening) to validate incoming requests. Correlation values do not authenticate the sender.

## States reference

| State | Description |
|  --- | --- |
| `Unknown` | State is not known or has not been mapped. |
| `Draft` | Communication prepared but not yet submitted. |
| `Submitted` | Accepted by the platform, pending document validation and processing. |
| `Processed` | Document validated and certified; send request dispatched to the postal operator. |
| `Dispatched` | Postal operator acknowledged receipt of the item. |
| `Issued` | Courier collected the item for physical delivery. Operator-specific; not all providers report this step. |
| `Sent` | Item is in transit with the postal operator or courier. |
| `Delivered` | Delivered to the recipient. For registered post, this requires the recipient's signature. |
| `Undelivered` | The operator reported non-delivery. This does not identify a collection or return action, and is not itself closure. See [Delivery attempts and non-delivery](#delivery-attempts-and-non-delivery). |
| `Missing` | Value exposed by the API contract; no normal transition into this state is defined by the current lifecycle implementation. Contact support if it appears. |
| `Disposed` | The provider reported destruction of the undelivered item under a service configured for disposal. |
| `Failed` | A processing or delivery failure occurred. |
| `Cancelled` | Cancellation was confirmed for a `Letter` with delivery tracking enabled. See [Key state transitions](#key-state-transitions) for the cancellation window. |
| `Closed` | Postal tracking is complete and the outcome is final. Affidavit publication can still follow. |


**For API integrators:** postal progress depends on operator reports, so allow hours or days between updates. Use the supported `PushNotificationFilter` values and Query reconciliation; avoid frequent polling. Platform validation, cancellation, and expiry can also affect the lifecycle.

Not all postal operators or service configurations report `Issued`. Do not depend on receiving an `Issued` callback before `Sent`.

## Outcomes reference

EviPost has postal outcomes that describe the results reported during physical delivery. While the communication is open, an outcome can be superseded. Read it together with the state; it is final when the state is `Closed`.

| Outcome | Description |
|  --- | --- |
| `Unknown` | Outcome not known or not yet mapped. |
| `None` | No outcome determined yet. |
| `Dispatched` | Item dispatched to the operator. Intermediate outcome, may be superseded. |
| `Acknowledged` | Value exposed by the API contract but not produced by the current lifecycle implementation. Contact support if it appears. |
| `Sent` | Item sent. This can be the final outcome for plain `Letter` without delivery receipt, attempt tracking, or disposal. |
| `Delivered` | Successfully delivered to the recipient. |
| `Declined` | Defined in the API contract and domain, but not emitted by the current postal event handlers. Recipient refusal is reported as `Rejected`. |
| `Rejected` | Recipient rejected the postal communication. |
| `Hindered` | Value exposed by the API contract but not produced by the current lifecycle implementation. Contact support if it appears. |
| `Undelivered` | Non-delivery was reported. Final only when the communication is `Closed`; it is not the result of every unsuccessful attempt. |
| `Disposed` | Destruction of the undelivered item was reported for a service configured for disposal. |
| `Expired` | Delivery could not be completed within the postal deadline. |
| `Cancelled` | Cancelled by the issuer. |
| `Failed` | A processing error prevented normal delivery. |


## Querying status

**For API integrators.** This section explains programmatic status checks. In the Web app, use [transaction search](/products/namirialnotify/issuer/transactions-search-evipost) and open the communication to view its history.

Use the Query endpoint as a fallback when callbacks lag or for batch reconciliation.


```
GET /v1/EviPost/Query
```

If `Limit` is omitted, the API defaults to `100`. The default drops to `25` when `IncludeAffidavitsOnResult` is true.

Common filters:

- `WithLookupKeys=your-key` — fetch by your correlation key.
- `WithUniqueIds=<UniqueId>` — fetch a specific communication by its ID.
- `OnState=Closed` — fetch only closed communications.


**State and outcome filters require support guidance**

`OnState` and `WithOutcome` filters are available but contact support before using them in production — some state transitions generate internal intermediate values that are not exposed in the documented enum.

## First-call walkthrough

**For API integrators.** The following steps use API requests and a callback endpoint.

This walkthrough takes you from zero to a completed EviPost with a downloaded affidavit. It covers the happy path: a registered postal communication sent to a single recipient.

### What you need

- API credentials for your environment
- A PDF document to send (base64-encoded)
- Recipient and issuer names, legal names, and physical addresses
- A dedicated non-production HTTPS endpoint that you control for callbacks; use synthetic data and follow the [callback testing guidance](/products/namirialnotify/dev/security-best-practices#callback-endpoint-hardening)


### Step 1 — Submit the postal communication


```bash
curl -X POST https://api.evicertia.com/v1/EviPost/Submit \
  -u "YOUR_USERNAME:YOUR_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "X-Evi-IdempotencyToken: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "LookupKey": "EVIPOST-TEST-001",
    "Document": "<base64-encoded PDF>",
    "RecipientName": "Alice Martin",
    "RecipientLegalName": "Alice Martin García",
    "RecipientAddress": {
      "StreetAddress": "Calle Mayor 10",
      "PostalCode": "28001",
      "Locality": "Madrid",
      "Country": "ES"
    },
    "IssuerName": "Acme Corp",
    "IssuerLegalName": "Acme Corporation S.L.",
    "IssuerAddress": {
      "StreetAddress": "Paseo de la Castellana 200",
      "PostalCode": "28046",
      "Locality": "Madrid",
      "Country": "ES"
    },
    "Options": {
      "PostServiceType": "Registered",
      "CertificationLevel": "Advanced_EU",
      "AffidavitProfile": "AdvancedContentOnSubmit",
      "PushNotificationUrl": "https://your-endpoint.example.com/callbacks/evipost",
      "PushNotificationFilter": ["Sent", "Delivered", "Closed", "AffidavitPublished"]
    }
  }'
```

A successful response returns the `uniqueId`:


```json
{
  "uniqueId": "69819c3e-0c0e-42b3-a792-a33b014a13a2"
}
```

Save this ID. It is your primary handle for all queries and callbacks.

### Step 2 — Verify the state progresses

Poll the Query endpoint to confirm the EviPost moves through `Submitted → Processed → Dispatched → Issued → Sent`:


```bash
curl "https://api.evicertia.com/v1/EviPost/Query?WithUniqueIds=69819c3e-0c0e-42b3-a792-a33b014a13a2" \
  -u "YOUR_USERNAME:YOUR_PASSWORD"
```

Expected response once submitted:


```json
{
  "totalMatches": 1,
  "results": [
    {
      "evidenceId": "69819c3e-0c0e-42b3-a792-a33b014a13a2",
      "lookupKey": "EVIPOST-TEST-001",
      "state": "Sent",
      "outcome": "None"
    }
  ]
}
```

EviPost tracks a physical postal delivery. `Sent` means the item was handed to the postal operator. Further state changes (`Delivered`, `Undelivered`, etc.) depend on the operator and can take days.

### Step 3 — Receive callbacks

Depending on the postal operator, you will receive callbacks for one or more source-supported filters such as `Sent`, `Delivered`, `Disposed`, and `Closed`. `Undelivered` is reflected in the Query response and final outcome data, not as a standalone push-filter value. When the postal process reaches its end, a `Closed` callback fires with `Outcome` in `AdditionalData`.

Do not assume `Closed` arrives immediately — postal lifecycles typically take days or weeks. Design your callback handler to handle each event independently.

### Step 4 — Download the affidavit

When you receive an `AffidavitPublished` callback, copy the `AffidavitId` from
its `AdditionalData`. You can also list generated affidavits and their IDs via
Query:


```bash
curl "https://api.evicertia.com/v1/EviPost/Query?WithUniqueIds=69819c3e-0c0e-42b3-a792-a33b014a13a2&IncludeAffidavitsOnResult=true&IncludeAffidavitBlobsOnResult=false" \
  -u "YOUR_USERNAME:YOUR_PASSWORD"
```

The response includes an `affidavits` array with metadata such as the affidavit
ID, generation date, description, and, where available, kind.

Callbacks contain metadata and identifiers, not the PDF. Setting the deprecated
`IncludeAffidavitBlobsOnResult` option to `false` keeps Query metadata-only.
Pass the affidavit ID to the shared download endpoint:


```bash
curl -X POST "https://api.evicertia.com/AffidavitsDownload" \
  -u "YOUR_USERNAME:YOUR_PASSWORD" \
  -H "Content-Type: application/json" \
  --data '{"UniqueIds":["000c1f70-42ac-a3ea-149f-943879726a87"]}' \
  --output affidavits.zip
```

Replace the sample UUID with the affidavit ID returned by your callback or
Query response. The endpoint returns a ZIP archive containing the signed PDF,
not a bare PDF response. See [Shared download APIs](/products/namirialnotify/apis/downloads-api#download-affidavit-pdfs-by-id)
for the complete response and error contract.

### Step 5 — Test the failure path

Re-run the walkthrough with a PDF that exceeds the allowed page count, or use an invalid address. Confirm that:

- the Submit returns a `400 Bad Request` with a `responseStatus` body describing the error
- no `UniqueId` is created for the failed request
- retrying with the same idempotency token and a corrected payload resubmits successfully


## Integration checklist

- Set `LookupKey` on every Submit and persist `uniqueId` from the response.
- Send `X-Evi-IdempotencyToken` (UUID) on every Submit. Treat `202 Accepted` as success.
- Set `AffidavitsOnDemandEnabled: true` at submit time if you may need to call `AffidavitRequest` later — this cannot be enabled retroactively.
- Subscribe to `AffidavitPublished` in `PushNotificationFilter` if you download affidavits programmatically.
- Design for an asynchronous, days-long lifecycle — do not expect state changes within minutes.
- Do not depend on `Issued` callbacks — plan for the direct `Dispatched → Sent` path since not all operators report this step.
- Make your callback handler idempotent, keyed on `Identifier`.
- Use Query as a fallback when callbacks lag — postal events can arrive in bursts or with delays.
- When using notary retention (`NotaryRetentionPeriod > 0`), always provide a valid `NotaryProfile`.


## Troubleshooting

The table below covers API integration issues. For Web app issues, see the [EviPost issuer guide](/products/namirialnotify/issuer/create-evipost#troubleshooting).

| Symptom | Likely causes | What to check | What to do |
|  --- | --- | --- | --- |
| Communication closed immediately as `Failed` | Invalid PDF document; page count exceeds subscribed tier | Submit `responseStatus.errors[]`; Query shows the failure state when an evidence was created | Fix the document and resubmit with a new idempotency token |
| No state changes after `Processed` | Postal operator has not yet acknowledged; normal for `Registered` type | `ProcessedOn` timestamp in Query | Wait — postal operator events can take hours |
| No `Issued` callback | Operator or service configuration does not report this step | `PostServiceType` in your submit request | Expected for some operators — continue monitoring for `Sent` |
| Communication stays in `Sent` for days | Postal processing or delivery is still in progress | `SentOn` timestamp; postal operator delivery timelines | Wait — do not resubmit. EviPost has no submit-configurable time-to-live; the lifecycle follows postal-operator timelines |
| `Undelivered` reported | Operator reported non-delivery; the reason depends on the shipment | Query state and outcome; operator details in the Web app event history or available affidavits | Check whether the communication is `Closed` and confirm the postal result before deciding whether to send a new communication |
| Affidavit not available | Generation is asynchronous; `AffidavitPublished` has not fired yet; profile does not generate affidavits for this event | Query with `IncludeAffidavitsOnResult=true` | Wait for `AffidavitPublished` callback |
| On-demand affidavit request rejected | `AffidavitsOnDemandEnabled` was not set to `true` at submission; `AffidavitProfile` is not Advanced | Original submit request | Cannot be enabled retroactively — resubmit with correct settings |
| Submit → `400 Bad Request` | Missing required field; invalid certification level; document too large or invalid format | `responseStatus.errors[]` | Fix flagged field; retry with new idempotency token |
| Submit → `401 Unauthorized` | Wrong environment URL; credentials rotated | `Authorization` header | Re-issue credentials |
| Submit → `403 Forbidden` | Account not provisioned for EviPost | Account permissions | Contact your Namirial Notify account manager |


## Related

- [EviPost API](/products/namirialnotify/apis/evipost-api)
- [How to create a new EviPost](/products/namirialnotify/issuer/create-evipost)
- [EviMail](/products/namirialnotify/services/evimail)
- [EviNotice](/products/namirialnotify/services/evinotice)
- [EviSMS](/products/namirialnotify/services/evisms)
- [API reference overview](/products/namirialnotify/apis/overview)
- [Callbacks and webhooks](/products/namirialnotify/dev/callbacks)
- [Security and authentication](/products/namirialnotify/dev/security-best-practices)
- [States and outcomes](/products/namirialnotify/user-guides/states-outcomes)
- [Evidence and affidavits](/products/namirialnotify/user-guides/evidences-affidavits)