# 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](/it/products/namirialnotify/issuer/create-evipost). For request and response definitions, see the [EviPost API reference](/it/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](/it/products/namirialnotify/services/evimail) when certified delivery via email is sufficient. Use [EviNotice](/it/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](/it/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 [checks the PDF](/it/products/namirialnotify/apis/evipost-api#document), certifies it, and dispatches a send request to the postal operator. PDF processing failures and postal-service rejections can close the communication with outcome `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. The operator must report delivery with proof. When delivery receipt tracking is off, a report without proof of delivery can set the state and outcome to `Failed` while still setting `deliveredOn`. Use the state and outcome to confirm 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` to learn when tracking ends, then read the final `outcome` from Query. 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](/it/products/namirialnotify/issuer/create-evipost) for the required-field checklist, screenshots of the form, and detailed instructions. After sending, use [EviPost transaction search](/it/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](/it/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. |
| `RecipientName` | Non-blank display name of the recipient. |
| `RecipientAddress` | Physical delivery address. See [Address fields](#address-fields). |


### Optional fields

- **`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. Supply both issuer names if you want them recorded; the API does not fill them from the account.
- **`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. Use `+` followed by the country code and phone number, with digits only (for example, `+34677888777`). Other formats return `400`.
- **`RecipientEmail`** — recipient's email address.
- **`IssuerPhone`** — sender's phone number. Use `+` followed by the country code and phone number, with digits only (for example, `+34677888777`). Other formats return `400`.
- **`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. Maximum 100 characters for the recipient and 255 for the issuer. |
| `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.

Set `CertificationLevel` and `EvidenceAccessControlMethod` explicitly. The API does not use the Web form’s account defaults for these fields. See [API options](/it/products/namirialnotify/apis/evipost-api#options) for conditional requirements.

- **`PostServiceType`** — `Registered` (default), `Letter`, or `LetterLite`. If omitted, defaults to `Registered`. See [Service types](#service-types) below.
- **`PostServiceProfile`** — Optional provider profile for `Letter`. Omit it unless support has given you a profile identifier.
- **`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 to `true` at Submit for an advanced affidavit profile if you plan to request affidavits on an open `Letter` or `LetterLite`. See [eligibility and limits](/it/products/namirialnotify/apis/evipost-api#request-an-on-demand-affidavit).
- **`OnlineRetentionPeriod`** — 1 to 20 years of online evidence retention. Currently 1 year by default.
- **`NotaryRetentionPeriod`** — set to `5` for five years of notarial custody or `0` to disable it. Any non-zero value applies five years.
- **`NotaryProfile`** — required when `NotaryRetentionPeriod > 0`; omit it otherwise. See the [profile format](/it/products/namirialnotify/apis/evipost-api#options).
- **`EvidenceAccessControlMethod`** — controls how the evidence record is accessed: `Public`, `Challenge`, `AutoChallenge` (defaults to `Public` in the API, with no access challenge). 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 callbacks. Set both `PushNotificationUrl` and a non-empty `PushNotificationFilter`, or omit both. Submit returns `400 Bad Request` if only one is set or if the filter repeats a value.
- **`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. Each field needs a non-blank `TypeName`. Do not combine `IsLookupKey: true` with a top-level `LookupKey`. See [custom field rules](/it/products/namirialnotify/apis/evipost-api#customfields).


### 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](/it/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 — omit the `Letter` receipt, delivery-attempt and disposal options.

### Letter

Sends the document to a printing and enveloping provider (MRW) for certified delivery. Supports optional delivery receipt, delivery attempts, and disposal:

- **`EnableDeliveryReceipt`** — request a signed delivery receipt from the provider.
- **`EnableDeliveryAttempts`** and **`DeliveryAttemptsNumber`** — send both `true` and a positive number to request attempts. The maximum is currently 2 by default.
- **`EnableDisposal`** and **`DisposalDaysAmmount`** — send `true` and 1 to 15 days to request disposal if the item remains undelivered. The field name retains its original spelling.


### 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 — omit both disposal options.
- Unavailable on sites billed per submission.


## 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. |


See [Request an on-demand affidavit](/it/products/namirialnotify/apis/evipost-api#request-an-on-demand-affidavit) for the supported service types, profile, open-state requirement, and configurable per-communication limit.

## 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 an event selected in `PushNotificationFilter` is published, Namirial Notify sends an HTTP POST to `PushNotificationUrl`.

### Base payload

| Field | Type | Description |
|  --- | --- | --- |
| `Identifier` | string | Lifecycle event ID or the affidavit ID used by the publisher. Retries retain it. |
| `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` | Issuer legal name followed by the display name, when supplied. |
| `Recipient` | Recipient legal name, when supplied, followed by the display name. |
| `LookupKey` | The integrator-assigned lookup key set at submission. |
| `State` | Current lifecycle state. |
| `CreationDate` | Timestamp when the communication was created. |


### 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` — human-readable text for the final outcome. Its language can vary. Use the Query `outcome` field for the outcome code. `CourierCode` — included when available. |
| `Disposed` | `CourierCode` — included when available. |
| `Cancelled` | `Success` — boolean: `true` confirms cancellation; `false` reports an unsuccessful cancellation attempt. The callback kind alone does not confirm cancellation. |
| `AffidavitPublished` | `AffidavitId` and `AffidavitName` — ID and description of the affidavit. `Regenerated: true` marks regeneration. The callback does not include the on-demand request ID. |


### Callback reliability

Deduplicate deliveries using `EvidenceType`, `EvidenceId`, `Kind`, and `Identifier`. A retry keeps the same payload. An `AffidavitPublished` callback can reuse that key when the affidavit is regenerated. If you track regenerated PDFs, check `AdditionalData.Regenerated` before dropping the callback as a duplicate. Reconcile the current affidavit IDs through Query and make that reconciliation safe to repeat. See [Handling callbacks reliably](/it/products/namirialnotify/dev/callbacks#handling-callbacks-reliably).

### Securing your callback endpoint

Use the shared [callback endpoint controls](/it/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 tracking timeouts 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` | Listed in the API contract, but not supported as the outcome of normal postal closure. A tracking timeout does not automatically assign this outcome. If it appears, check the current state with Query and contact support. |
| `Cancelled` | The postal operator confirmed the issuer's cancellation request. |
| `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](/it/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
```

See the [Query limits and affidavit options](/it/products/namirialnotify/apis/evipost-api#query-certified-postal-communications). Send `IncludeAffidavitBlobsOnResult=false` explicitly for metadata only.

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](/it/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",
      "Region": "Madrid",
      "Country": "ES"
    },
    "IssuerName": "Acme Corp",
    "IssuerLegalName": "Acme Corporation S.L.",
    "IssuerAddress": {
      "StreetAddress": "Paseo de la Castellana 200",
      "PostalCode": "28046",
      "Locality": "Madrid",
      "Region": "Madrid",
      "Country": "ES"
    },
    "Options": {
      "PostServiceType": "Registered",
      "CertificationLevel": "Advanced_EU",
      "EvidenceAccessControlMethod": "AutoChallenge",
      "AffidavitProfile": "AdvancedContentOnSubmit",
      "PushNotificationUrl": "https://your-endpoint.example.com/callbacks/evipost",
      "PushNotificationFilter": ["Sent", "Delivered", "Closed", "AffidavitPublished"]
    }
  }'
```

A successful response returns the `uniqueId`:

```json
{
  "uniqueId": "69819c3e0c0e42b3a792a33b014a13a2"
}
```

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

### Step 2 — Verify the state progresses

Use Query to check which milestones the service has recorded. For example, an item can reach `Sent` from `Dispatched` without passing through `Issued`:

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

Example response after `Sent` has been recorded:

```json
{
  "totalMatches": 1,
  "results": [
    {
      "evidenceId": "69819c3e0c0e42b3a792a33b014a13a2",
      "lookupKey": "EVIPOST-TEST-001",
      "state": "Sent",
      "outcome": "Sent"
    }
  ]
}
```

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. When matching a callback to Query, compare the dashed callback ID and the dash-free Query ID as UUIDs.

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](/it/products/namirialnotify/apis/downloads-api#download-affidavit-pdfs-by-id)
for the complete response and error contract.

### Step 5 — Test the failure path

Test an invalid recipient address to exercise a synchronous `400 Bad Request`. A different failure can occur after Submit returns `200 OK`: for example, a PDF with embedded files can fail during processing. If Submit returns an ID, use Query to check whether the communication closes with outcome `Failed` before deciding whether to submit again.

## 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.
- For an open `Letter` or `LetterLite`, configure [on-demand affidavit eligibility](/it/products/namirialnotify/apis/evipost-api#request-an-on-demand-affidavit) at Submit.
- 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. Follow [callback reliability](#callback-reliability).
- 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](/it/products/namirialnotify/issuer/create-evipost#troubleshooting).

| Symptom | Likely causes | What to check | What to do |
|  --- | --- | --- | --- |
| Query shows `Closed` with outcome `Failed` | PDF processing, billing tier validation, or postal-service rejection | Query and the transaction event history | Resolve the recorded failure before sending a new communication |
| 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 for the next update. See the [tracking window and timeout behavior](/it/products/namirialnotify/apis/evipost-api#query-certified-postal-communications) |
| `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 | Ineligible service type, state, or submit options; per-communication limit reached | Original request and current Query state | Check [eligibility and limits](/it/products/namirialnotify/apis/evipost-api#request-an-on-demand-affidavit) |
| 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](/it/products/namirialnotify/apis/evipost-api)
- [How to create a new EviPost](/it/products/namirialnotify/issuer/create-evipost)
- [EviMail](/it/products/namirialnotify/services/evimail)
- [EviNotice](/it/products/namirialnotify/services/evinotice)
- [EviSMS](/it/products/namirialnotify/services/evisms)
- [API reference overview](/it/products/namirialnotify/apis/overview)
- [Callbacks and webhooks](/it/products/namirialnotify/dev/callbacks)
- [Security and authentication](/it/products/namirialnotify/dev/security-best-practices)
- [States and outcomes](/it/products/namirialnotify/user-guides/states-outcomes)
- [Evidence and affidavits](/it/products/namirialnotify/user-guides/evidences-affidavits)