Skip to content
Last updated

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. For request and response definitions, see the EviPost API reference.


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 when certified delivery via email is sufficient. Use 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 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

Submit accepted

Document validated and certified

Invalid document (Failed)

Postal operator acknowledged

Item issued by provider

Item sent

Item sent (direct)

Delivery reported

Non-delivery reported

Plain Letter (Sent) or Registered (Rejected)

Letter configured for disposal

Letter with a later failure report

Registered or LetterLite final non-delivery

Processing or delivery failure

Final delivery result

Final disposal result

Final failure result

Tracked Letter cancellation confirmed

Final cancellation result

Submitted

Processed

Closed

Dispatched

Issued

Sent

Delivered

Undelivered

Disposed

Failed

Cancelled

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.

Submit accepted

Document validated and certified

Invalid document (Failed)

Postal operator acknowledged

Item issued by provider

Item sent

Item sent (direct)

Delivery reported

Non-delivery reported

Plain Letter (Sent) or Registered (Rejected)

Letter configured for disposal

Letter with a later failure report

Registered or LetterLite final non-delivery

Processing or delivery failure

Final delivery result

Final disposal result

Final failure result

Tracked Letter cancellation confirmed

Final cancellation result

Submitted

Processed

Closed

Dispatched

Issued

Sent

Delivered

Undelivered

Disposed

Failed

Cancelled

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.

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

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 happenedHow to interpret it
An individual delivery attempt failedA 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 UndeliveredNon-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 receivedRegistered 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 returnedDo 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.


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 for the required-field checklist, screenshots of the form, and detailed instructions. After sending, use EviPost transaction search 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.

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

FieldDescription
DocumentThe letter or document to be sent, base64-encoded PDF.
RecipientNameNon-blank display name of the recipient.
RecipientAddressPhysical delivery address. See 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.
  • Options — processing and certification settings. When omitted, platform defaults apply. See 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:

FieldRequiredDescription
StreetAddressYesStreet name and number. Maximum 100 characters for the recipient and 255 for the issuer.
PostalCodeYesPostal code.
LocalityYesCity or town.
CountryYesISO 3166-1 alpha-2 country code (e.g. ES).
RegionConditionalProvince or region. Required in RecipientAddress for Registered. The issuer region must also be present, either supplied in IssuerAddress or filled from the site address.
PostOfficeBoxAddressNoPost 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 for conditional requirements.

  • PostServiceType — Registered (default), Letter, or LetterLite. If omitted, defaults to Registered. See 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 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.
  • 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.
  • 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.

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.

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:

ValueDescription
NoneNo affidavits generated.
BasicA single receipt affidavit when tracking is complete. Default for Standard certification.
AdvancedContentOnSubmitOne affidavit per event, plus a timestamped content affidavit at submission. Default for Advanced certification.
AdvancedContentOnCloseOne affidavit per event, plus a receipt showing the document body when tracking is complete.
AdvancedContentOnSubmitAndOnCloseCombination of the above two.

See 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

FieldTypeDescription
IdentifierstringLifecycle event ID or the affidavit ID used by the publisher. Retries retain it.
KindstringThe state or event that triggered this callback (e.g. Dispatched, Sent, Delivered, Closed).
DatedatetimeTimestamp of the event.
EvidenceIdUUIDThe UniqueId of the EviPost, as returned at submission.
EvidenceTypestringAlways eviPost for EviPost callbacks.
EvidenceStatestring/nullNot populated by this service. Accept an absent or null value and use AdditionalData.State.
SitestringName of the issuer's site.
Ownerstring/nullNot populated by this service. Accept an absent or null value; do not require it.
OwnerEmailstringEmail address of the account owner.
AdditionalDataobjectCommon and event-specific fields described below.

AdditionalData fields — always present

FieldDescription
SenderIssuer legal name followed by the display name, when supplied.
RecipientRecipient legal name, when supplied, followed by the display name.
LookupKeyThe integrator-assigned lookup key set at submission.
StateCurrent lifecycle state.
CreationDateTimestamp 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 KindExtra fields
Dispatched, Sent, IssuedTransmissionDetails — postal operator transmission details for this event.
DeliveredDetails — delivery details reported by the postal operator.
ClosedOutcome — human-readable text for the final outcome. Its language can vary. Use the Query outcome field for the outcome code. CourierCode — included when available.
DisposedCourierCode — included when available.
CancelledSuccess — boolean: true confirms cancellation; false reports an unsuccessful cancellation attempt. The callback kind alone does not confirm cancellation.
AffidavitPublishedAffidavitId 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.

Securing your callback endpoint

Use the shared callback endpoint controls to validate incoming requests. Correlation values do not authenticate the sender.


States reference

StateDescription
UnknownState is not known or has not been mapped.
DraftCommunication prepared but not yet submitted.
SubmittedAccepted by the platform, pending document validation and processing.
ProcessedDocument validated and certified; send request dispatched to the postal operator.
DispatchedPostal operator acknowledged receipt of the item.
IssuedCourier collected the item for physical delivery. Operator-specific; not all providers report this step.
SentItem is in transit with the postal operator or courier.
DeliveredDelivered to the recipient. For registered post, this requires the recipient's signature.
UndeliveredThe operator reported non-delivery. This does not identify a collection or return action, and is not itself closure. See Delivery attempts and non-delivery.
MissingValue exposed by the API contract; no normal transition into this state is defined by the current lifecycle implementation. Contact support if it appears.
DisposedThe provider reported destruction of the undelivered item under a service configured for disposal.
FailedA processing or delivery failure occurred.
CancelledCancellation was confirmed for a Letter with delivery tracking enabled. See Key state transitions for the cancellation window.
ClosedPostal 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.

OutcomeDescription
UnknownOutcome not known or not yet mapped.
NoneNo outcome determined yet.
DispatchedItem dispatched to the operator. Intermediate outcome, may be superseded.
AcknowledgedValue exposed by the API contract but not produced by the current lifecycle implementation. Contact support if it appears.
SentItem sent. This can be the final outcome for plain Letter without delivery receipt, attempt tracking, or disposal.
DeliveredSuccessfully delivered to the recipient.
DeclinedDefined in the API contract and domain, but not emitted by the current postal event handlers. Recipient refusal is reported as Rejected.
RejectedRecipient rejected the postal communication.
HinderedValue exposed by the API contract but not produced by the current lifecycle implementation. Contact support if it appears.
UndeliveredNon-delivery was reported. Final only when the communication is Closed; it is not the result of every unsuccessful attempt.
DisposedDestruction of the undelivered item was reported for a service configured for disposal.
ExpiredListed 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.
CancelledThe postal operator confirmed the issuer's cancellation request.
FailedA processing error prevented normal delivery.

Querying status

For API integrators. This section explains programmatic status checks. In the Web app, use transaction search 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. 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

Step 1 — Submit the postal communication

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:

{
  "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:

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:

{
  "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:

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:

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

SymptomLikely causesWhat to checkWhat to do
Query shows Closed with outcome FailedPDF processing, billing tier validation, or postal-service rejectionQuery and the transaction event historyResolve the recorded failure before sending a new communication
No state changes after ProcessedPostal operator has not yet acknowledged; normal for Registered typeProcessedOn timestamp in QueryWait — postal operator events can take hours
No Issued callbackOperator or service configuration does not report this stepPostServiceType in your submit requestExpected for some operators — continue monitoring for Sent
Communication stays in Sent for daysPostal processing or delivery is still in progressSentOn timestamp; postal operator delivery timelinesWait for the next update. See the tracking window and timeout behavior
Undelivered reportedOperator reported non-delivery; the reason depends on the shipmentQuery state and outcome; operator details in the Web app event history or available affidavitsCheck whether the communication is Closed and confirm the postal result before deciding whether to send a new communication
Affidavit not availableGeneration is asynchronous; AffidavitPublished has not fired yet; profile does not generate affidavits for this eventQuery with IncludeAffidavitsOnResult=trueWait for AffidavitPublished callback
On-demand affidavit request rejectedIneligible service type, state, or submit options; per-communication limit reachedOriginal request and current Query stateCheck eligibility and limits
Submit → 400 Bad RequestMissing required field; invalid certification level; document too large or invalid formatresponseStatus.errors[]Fix flagged field; retry with new idempotency token
Submit → 401 UnauthorizedWrong environment URL; credentials rotatedAuthorization headerRe-issue credentials
Submit → 403 ForbiddenAccount not provisioned for EviPostAccount permissionsContact your Namirial Notify account manager