EviPost API

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

The EviPost API lets you submit certified physical postal communications (equivalent to a burofax) and query the status of previously submitted items. It is a REST API that uses HTTP Basic authentication and returns JSON responses.

For end-to-end lifecycle, postal service types, and integration guidance, see the EviPost service guide.

Environments

For the public Namirial Notify API environments, this V1 service is exposed under the /v1 base path. Use public routes such as /v1/EviPost/Submit, /v1/EviPost/Query, and /v1/EviPost/AffidavitRequest.

Some lower-level technical artifacts may show these V1 routes without the /v1 prefix. For customer integrations, use the public /v1 base path shown in this documentation.

For shared environment guidance across services, see the API reference overview.

Authentication

All endpoints require HTTP Basic authentication. Pass your Namirial Notify credentials as the username and password in the Authorization header.

Authorization: Basic <base64(username:password)>

See credential handling, callback endpoint hardening, and operational security checks.

Idempotency

EviPost Submit supports idempotent submission. Include the X-Evi-IdempotencyToken header with a unique value per logical operation (a GUID is recommended).

If the same token is submitted again after the original request completed with 200 OK, the server returns 202 Accepted with the original response body — the communication is not resubmitted.

The following response codes are not cached and will re-execute the request regardless of token: 400, 401, 408, 409, 429, and 5xx responses.

Error responses

EviPost v1 uses a responseStatus object for error responses.

{
  "responseStatus": {
    "errorCode": "ArgumentException",
    "message": "RecipientAddress.Country is required.",
    "errors": [
      {
        "errorCode": "NotEmpty",
        "fieldName": "RecipientAddress.Country",
        "message": "RecipientAddress.Country is required."
      }
    ]
  }
}

Common status codes and their causes:

For shared error handling guidance, see Error handling.

Endpoints

Submit a certified postal communication

POST /v1/EviPost/Submit

Submits a new certified postal communication. On success, returns a UniqueId that identifies the submission and can be used to query its status later.

Required fields: Document (base64-encoded PDF), RecipientAddress.

Optional fields include RecipientName, RecipientLegalName, IssuerName, IssuerLegalName, IssuerAddress, Options, LookupKey, RecipientPhone, RecipientEmail, IssuerPhone, IssuerEmail, and IssuerComments.

See Idempotency above for retry safety guidance.

Example request:

POST /v1/EviPost/Submit HTTP/1.1
Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Content-Type: application/json

{
  "LookupKey": "a2R4S25kWiu79fsbubSXkw==",
  "Document": "<base64-encoded PDF>",
  "RecipientName": "Juan Valido",
  "RecipientLegalName": "Juan Valido",
  "RecipientAddress": {
    "StreetAddress": "Gran Via 74, 5 A",
    "PostalCode": "28014",
    "Locality": "Madrid",
    "Region": "Madrid",
    "Country": "ES"
  },
  "IssuerName": "Pedro Comprador",
  "IssuerLegalName": "Pedro Valido",
  "IssuerAddress": {
    "StreetAddress": "C/ Gran Via, 1, 1-A",
    "PostalCode": "28001",
    "Locality": "Madrid",
    "Region": "Madrid",
    "Country": "ES"
  },
  "IssuerPhone": "+34677888777",
  "IssuerEmail": "pedro.comprador@example.com",
  "IssuerComments": "Sending in March.",
  "Options": {
    "PostServiceType": "Registered",
    "CertificationLevel": "Advanced_EU",
    "NotaryRetentionPeriod": 5,
    "OnlineRetentionPeriod": 1
  }
}

Example response:

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

Query certified postal communications

GET /v1/EviPost/Query

Returns a list of postal communications matching the specified filters. Results are paginated using Limit and Offset.

Query parameters:

If Limit is omitted, the API uses a default of 100. The default drops to 25 when IncludeAffidavitsOnResult is true.

With the deprecated IncludeAffidavitBlobsOnResult=false, IncludeAffidavitsOnResult=true adds affidavit metadata and IDs without embedding the PDF files. Pass the returned affidavit IDs to the shared /AffidavitsDownload endpoint to retrieve the signed PDFs in a ZIP archive. This is the recommended retrieval flow for new integrations.

Example request:

GET /v1/EviPost/Query?WithUniqueIds=3977d143-a6cb-4642-abc6-a33b016cbec2&IncludeAffidavitsOnResult=true&IncludeAffidavitBlobsOnResult=false HTTP/1.1
Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==

Example response:

{
  "results": [
    {
      "evidenceId": "3977d143-a6cb-4642-abc6-a33b016cbec2",
      "lookupKey": "a2R4S25kWiu79fsbubSXkw==",
      "recipientName": "Juan Valido",
      "address": {
        "streetAddress": "Gran Via 74, 5 A",
        "postalCode": "28014",
        "locality": "Madrid",
        "region": "Madrid",
        "country": "ES"
      },
      "state": "Sent",
      "stateDate": "2026-01-15T10:00:07Z",
      "lastStateChangeDate": "2026-01-15T10:00:11Z",
      "outcome": "None",
      "outcomeDate": "2026-01-15T10:00:00Z",
      "creationDate": "2026-01-15T10:00:00Z",
      "submittedOn": "2026-01-15T10:00:00Z",
      "processedOn": "2026-01-15T10:00:03Z",
      "sentOn": "2026-01-15T10:00:07Z",
      "timeToLive": 43200,
      "costCentre": "dept-legal",
      "affidavits": [
        {
          "uniqueId": "000c1f70-42ac-a3ea-149f-943879726a87",
          "date": "2026-01-15T10:00:12Z",
          "evidenceUniqueId": "3977d143-a6cb-4642-abc6-a33b016cbec2",
          "description": "Certification of postal communication"
        }
      ]
    }
  ],
  "totalMatches": 1
}

Request an on-demand affidavit

POST /v1/EviPost/AffidavitRequest

Generates a custom affidavit for a previously submitted EviPost. To use this endpoint, AffidavitsOnDemandEnabled: true must have been set in the original Submit request.

Request body:

Example request:

POST /v1/EviPost/AffidavitRequest HTTP/1.1
Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Content-Type: application/json

{
  "UniqueId": "87ffa214-e773-4bd5-9b8d-a8ef00fd80f8",
  "IncludeDocument": true,
  "IncludeEvents": true
}

Example response:

{
  "requestId": "79726a87000c1f7042aca3ea149f9438"
}

Cancel a postal communication

POST /v1/EviPost/Cancel

Cancels a previously submitted EviPost that has not yet been dispatched to the postal carrier. Only the account that originally submitted the postal communication can cancel it.

Request body:

Example request:

POST /v1/EviPost/Cancel HTTP/1.1
Authorization: Basic XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX==
Content-Type: application/json

{
  "UniqueId": "69819c3e-0c0e-42b3-a792-a33b014a13a2"
}

Example response:

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

States and outcomes

For a cross-service explanation of lifecycle terminology, see States and outcomes. For a visual lifecycle reference, see the EviPost evidence lifecycle.

States represent the current step in the postal communication lifecycle.

Outcomes represent the result recorded so far and can change while the communication remains open. Use the outcome at Closed as the final result.

An individual delivery-attempt event does not itself change the state to Undelivered. For Registered and Letter with delivery tracking enabled, the platform accepts a later valid delivery report before closure; whether an operator emits that sequence is unconfirmed. LetterLite cannot complete normal closure with Delivered once non-delivery has been recorded. A Letter workflow configured for disposal can continue to Disposed; a later failure report for Letter can instead lead to Failed before closure. Registered and LetterLite can close with a final Undelivered outcome. See Delivery attempts and non-delivery for operator details and callback guidance.

Key request fields

Document

The document or letter to be sent, provided as a base64-encoded PDF string.

RecipientAddress / IssuerAddress

Both address objects share the same shape:

Options

The Options object groups all processing and certification settings.

PostServiceType

Controls the type of postal delivery. EviPost physical delivery is currently available for destinations within Spain; availability of each type depends on your account provisioning.

• Registered — Default. Sends a certified postal communication equivalent to a burofax, delivered through the national postal operator (Correos). Delivery attempts are handled by the operator and are not configured in the submit request.
• Letter — Sends to a printing and enveloping provider (MRW). Requires prior provisioning by support and a PostServiceProfile. Supports optional delivery receipt and delivery attempt tracking.
• LetterLite — A lower-cost single-attempt printed certified letter (MRW). Available only within mainland Spain (the islands, Ceuta, Melilla, Portugal, Andorra, and Gibraltar are excluded). The delivery-attempt and disposal options cannot be used, and PostServiceProfile is not required.

CertificationLevel

Defines the legal framework and geographic variant for certification. The API accepts Standard, Advanced, and regional values such as Standard_EU, Advanced_EU, Standard_CO, or Advanced_MX. Availability depends on the account. EviPost does not support QERDS certification levels.

AffidavitProfile

Controls what affidavits are generated during the process:

PushNotificationFilter

An array of event names that trigger a callback to PushNotificationUrl. Valid values for EviPost: Processed, Dispatched, Sent, Delivered, Closed, Cancelled, Issued, Disposed, AffidavitPublished.

AffidavitPublished is not a lifecycle state — it is a platform meta-event that fires when affidavit generation for this communication completes.

PushNotificationExtraData

A free-text field for additional data to be included in every push notification sent to PushNotificationUrl. Available in the AdditionalData.ExtraData field of the callback payload.

CustomFields

An array of custom key-value fields attached to the submission. Each field requires Key, Label, and Value. Fields marked with IsLookupKey: true are indexed and surfaced in query results under LookupKey, concatenated with :: if multiple values are present.

Push notification payload

When an EviPost changes state, Namirial Notify sends a POST to PushNotificationUrl with the following JSON payload:

Common fields:

AdditionalData fields:

For Dispatched and Sent events, AdditionalData also includes TransmissionDetails. For Delivered, it includes Details. For Closed, it includes Outcome.

Example payload (Processed event):

{
  "Identifier": "600a41fd-d96b-4c4b-abb2-a87000d7da3f",
  "EvidenceId": "bae409d127de4b18b97ca87000c75b1c",
  "EvidenceType": "eviPost",
  "Kind": "Processed",
  "Date": "2018-01-22T12:05:53.5875507Z",
  "Site": "pruebas",
  "Owner": "Pruebas evicertia",
  "OwnerEmail": "pruebas@evicertia.com",
  "AdditionalData": {
    "Sender": "Pedro Comprador",
    "Recipient": "Juan Valido",
    "LookupKey": "push-notification-test",
    "State": "Processed",
    "CreationDate": "2018-01-22T13:05:49.9850990+01:00",
    "ExtraData": "{\"myId\": \"99cf386b-1590-4ddb-af68-607b3e7c1194\"}"
  }
}

On-demand affidavit callback

When an affidavit requested via AffidavitRequest has been generated, Namirial Notify may send the normal AffidavitPublished push notification to the PushNotificationUrl configured on the original submission, when the original PushNotificationFilter includes AffidavitPublished. For on-demand affidavits, the payload can include the request identifier in AdditionalData.RequestId.

Example payload:

{
  "Identifier": "1234",
  "EvidenceId": "2aca3ea149f943879726a87000c1f704",
  "EvidenceType": "eviPost",
  "Kind": "AffidavitPublished",
  "Date": "2018-01-22T12:46:32.4830752+01:00",
  "Site": "pruebas",
  "Owner": "Pruebas evicertia",
  "OwnerEmail": "pruebas@evicertia.com",
  "AdditionalData": {
    "RequestId": "79726a87000c1f7042aca3ea149f9438",
    "AffidavitId": "000c1f7042aca3ea149f943879726a87",
    "AffidavitName": "Certification of postal communication (upon request)"
  }
}

OpenAPI specification

The OpenAPI 3.0.3 specification for the EviPost API provides a machine-readable definition of the service endpoints, request and response schemas, authentication method, and error responses.

Covered in the specification:

• Submit endpoint (POST /v1/EviPost/Submit) — detailed request and response schemas, idempotency headers, validation rules, and HTTP status codes
• Query endpoint (GET /v1/EviPost/Query) — pagination parameters, filtering by ID or lookup key, state and outcome enums, and result structure
• Affidavit request endpoint (POST /v1/EviPost/AffidavitRequest) — on-demand affidavit generation
• Authentication — HTTP Basic authentication requirements
• Error handling — V1 service-style error responses with responseStatus object containing errorCode, message, and errors
• Data types — schema definitions for documented addresses, postal options, certification levels, and evidence metadata

The OpenAPI spec can be used to generate client libraries, integration tests, or interactive API documentation.

View OpenAPI spec →

Related

• EviPost
• EviMail API
• EviNotice API
• EviSMS API
• API reference overview
• Callbacks and webhooks
• Error handling
• Integration workflows
• Security and authentication
• States and outcomes
• Evidence and affidavits