# EviPost

EviPost is the Namirial Notify service for sending certified physical postal communications — the digital equivalent of a burofax. The document is physically printed and delivered to the recipient's address by the postal operator, with each step in the postal process recorded as evidence and optionally generating a signed affidavit.

For the API reference, see the [EviPost API](/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 legally binding evidence of physical delivery** — the postal operator reports delivery outcomes that feed into certified affidavits.
- **The communication cannot be sent digitally** — for jurisdictions or situations where certified physical mail (burofax equivalent) carries specific legal weight.


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 recipient authentication and commitment workflows. Use [EviSMS](/products/namirialnotify/services/evisms) for certified mobile delivery.

:::warning Timeline expectation
EviPost operates on postal timelines — days or weeks, not minutes. Design your integration to accommodate asynchronous state updates driven by postal operator events rather than immediate confirmation.
:::

## 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, dispatched to postal operator
    Submitted --> Closed : Invalid document (Failed)
    Processed --> Dispatched : Postal operator acknowledged
    Dispatched --> Issued : Courier collected the item
    Issued --> Sent : Item in transit
    Dispatched --> Sent : Item in transit (direct)
    Sent --> Delivered : Delivered to recipient
    Sent --> Undelivered : Delivery not possible
    Undelivered --> Disposed : Item disposed after failed delivery
    Sent --> Failed : Postal operator reported failure
    Delivered --> Closed : Lifecycle complete
    Undelivered --> Closed : Lifecycle complete
    Disposed --> Closed : Lifecycle complete
    Failed --> Closed : Lifecycle complete
    Dispatched --> Cancelled : Cancelled by issuer
    Issued --> Cancelled : Cancelled by issuer
    Sent --> Cancelled : Cancelled by issuer
    Cancelled --> Closed : Lifecycle complete
```

### Key state transitions

**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 profiles 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 (burofax), this requires the recipient to sign for delivery.

**Sent → Undelivered** — The postal operator could not complete delivery. The item may be held at a post office or returned.

**Undelivered → Disposed** — The item was disposed of after the retention period at the post office expired.

**Any state → Cancelled** — The issuer explicitly cancelled the communication via the platform before delivery was completed.

## Submit a certified postal communication


```
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` | Display name of the recipient. |
| `RecipientLegalName` | Legal name of the recipient, recorded in the certification evidence. |
| `RecipientAddress` | Physical delivery address. See [Address fields](#address-fields). |
| `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. See [Options](#options). |


### Optional fields

- **`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` | No | Province or region. |
| `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` becomes `Default`. The web portal's submission form presents these same settings with a default already selected, so a value is always recorded whichever channel you use. 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. Use `Standard:EU` or `Advanced:EU` in new integrations, plus the country-specific variants supported by your account. `Standard` and `Advanced` are legacy aliases. 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: `Default` (the default if omitted), `Public`, `Challenge`, `AutoChallenge`. 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 (default)

Sends a certified postal communication equivalent to a burofax, delivered 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 standard choice for most integrations.

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 — `EnableDisposal` and `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

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

### Base payload

| Field | Type | Description |
|  --- | --- | --- |
| `Identifier` | string | Unique ID of this callback delivery. Use it to deduplicate — the platform retries on non-2xx and on timeouts. |
| `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. |
| `Site` | string | Name of the issuer's site. |
| `Owner` | string | Name of the account owner. |
| `OwnerEmail` | string | Email address of the account owner. |
| `AdditionalData` | object | Event-specific fields. Always includes the fields listed 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. |
| `ExtraData` | The `PushNotificationExtraData` value set at submission, if provided. |


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

Make your handler idempotent, keyed on `Identifier`. Return `2xx` promptly. Use `PushNotificationExtraData` to embed a routing key for correlation.

## 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` | Delivery was not possible. Item may be held at a post office or returned. |
| `Missing` | Item cannot be located by the postal operator. Operator-specific intermediate state. |
| `Disposed` | Item disposed of after the post-office retention period expired following an undelivered outcome. |
| `Failed` | A processing or delivery failure occurred. |
| `Cancelled` | Communication was cancelled by the issuer before delivery was completed. |
| `Closed` | Lifecycle complete. No further events expected. |


**On timeline:** state changes after `Processed` are driven entirely by postal operator events. Expect hours or days between transitions. Do not poll aggressively — use `PushNotificationFilter` to subscribe to the transitions you care about and use Query only as a fallback.

**On `Issued`:** not all postal operators or service profiles report this step. Your integration must not depend on receiving an `Issued` callback — plan for the direct `Dispatched → Sent` path.

## Outcomes reference

EviPost is the only Namirial Notify service with a distinct set of postal outcomes, reflecting the range of physical delivery results reported by operators:

| 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` | Postal operator acknowledged receipt. Operator-specific intermediate outcome. |
| `Sent` | Item sent and in transit. |
| `Delivered` | Successfully delivered to the recipient. |
| `Declined` | Recipient refused acceptance of the postal communication. |
| `Rejected` | Recipient rejected the postal communication. |
| `Hindered` | Delivery was hindered by an external circumstance. |
| `Undelivered` | Delivery was not possible. |
| `Disposed` | Item disposed of after an undelivered or returned outcome. |
| `Expired` | Delivery could not be completed within the postal deadline. |
| `Cancelled` | Cancelled by the issuer. |
| `Failed` | A processing error prevented normal delivery. |


## Querying status

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


```
GET  /v1/EviPost/Query
POST /v1/EviPost/Query
HEAD /v1/EviPost/Query
```

If `Limit` is omitted, the API defaults to `100`. The default drops to `25` when `IncludeAffidavitsOnResult` is true, and to `1` when `IncludeAffidavitBlobsOnResult` 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.


:::warning 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

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 reachable HTTPS endpoint for callbacks, or a tool such as [webhook.site](https://webhook.site) for testing


### 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 of `Sent`, `Delivered`, `Undelivered`, and `Closed`. 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, use the `AffidavitId` from its `AdditionalData` to retrieve the PDF:


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

The response includes an `affidavits` array with base64-encoded PDF content for each generated affidavit.

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

| Symptom | Likely causes | What to check | What to do |
|  --- | --- | --- | --- |
| Communication closed immediately as `Failed` | Invalid PDF document; page count exceeds subscribed tier | `Failed` callback and `responseStatus.errors[]` on Submit | 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 profile does not report this step | `PostServiceType` in your submit request | Expected for some operators — continue monitoring for `Sent` |
| Communication stays in `Sent` for days | Normal for international or standard postal delivery | `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` outcome received | Recipient not at address; address incorrect; delivery limit reached | `Details` in the `Delivered` callback; `Undelivered` callback | Contact recipient; consider resubmitting to a corrected address |
| 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 documentation](/products/namirialnotify/dev/api-documentation)
- [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)