Passer au contenu
Dernière mise à jour

EviNotice

EviNotice is the Namirial Notify certified hosted notice service. When you submit a notice, Namirial Notify sends a delivery notification to the recipient via email, SMS, RCS, or WhatsApp, and hosts the certified content on a secure platform page. Every step — delivery, access, reading, acceptance, rejection, or refusal — is recorded as evidence and optionally generates a signed affidavit.

This page explains EviNotice behaviour and includes guidance for API integrators. To send from the Web app, follow How to create a new EviNotice. For request and response definitions, see the EviNotice API reference.


When to use EviNotice

Use EviNotice when:

  • You need controlled access to the content — the recipient must authenticate before reading, using a challenge question, a mobile PIN, or an email PIN.
  • You need acceptance or rejection on record — the recipient can explicitly accept, reject, or refuse the notice, generating legally binding evidence of their decision.
  • You need to certify what the recipient saw — the notice content is hosted on Namirial Notify and certified there, so the evidence covers both delivery of the notification and the recipient's interaction with the content.
  • You need recipient identity verification — QeRDS requires a verified recipient identity before the recipient can read the notice. See QeRDS with EviNotice for the qualified-delivery requirements.

Use EviMail instead when the certified content should arrive directly in the recipient's inbox without requiring them to follow a link. Use EviSMS when the certified communication is the SMS message itself rather than a hosted document.


How the pieces fit together

An EviNotice involves two distinct layers:

  1. The notification channel — how the platform alerts the recipient. This can be email, SMS, RCS, or WhatsApp. The notification contains a secure link to the hosted notice.
  2. The hosted notice — the actual certified content, living on Namirial Notify. The recipient clicks through to read it, and all on-platform interactions are recorded as evidence.

This separation is why EviNotice has more lifecycle states than EviMail or EviSMS: Delivered refers to the notification reaching the recipient's device; Received refers to the recipient following the link; Read refers to the recipient opening the content on the platform.

Submit

Notification
email / SMS / RCS / WhatsApp

Clicks secure link

Reads, accepts, rejects, or refuses

Your system

Namirial Notify

Recipient

Hosted notice page

Evidence chain

Affidavits

Submit

Notification
email / SMS / RCS / WhatsApp

Clicks secure link

Reads, accepts, rejects, or refuses

Your system

Namirial Notify

Recipient

Hosted notice page

Evidence chain

Affidavits


How EviNotice works

Lifecycle overview

Submit accepted

Initial validation passed, content certified

Rejected during background processing

Notification send request issued

Successful transmission confirmed

Delivery confirmation received

Recipient follows hosted notice link

Link accessed without delivery feedback

Recipient opens notice content

Recipient accepts or rejects

No commitment and tracking to TTL not enforced

Tracking to TTL not enforced

Refused on landing page

Transmission failure

Delivery failure

Link access while open

Final outcome Failed

TimeToLive elapsed

Submitted

Processed

Failed

Dispatched

Sent

Delivered

Received

Read

Replied

Closed

Submit accepted

Initial validation passed, content certified

Rejected during background processing

Notification send request issued

Successful transmission confirmed

Delivery confirmation received

Recipient follows hosted notice link

Link accessed without delivery feedback

Recipient opens notice content

Recipient accepts or rejects

No commitment and tracking to TTL not enforced

Tracking to TTL not enforced

Refused on landing page

Transmission failure

Delivery failure

Link access while open

Final outcome Failed

TimeToLive elapsed

Submitted

Processed

Failed

Dispatched

Sent

Delivered

Received

Read

Replied

Closed

State: Failed can be recoverable and is not final by itself. A failure during initial processing closes the notice immediately; later failures can recover while the notice remains open. Wait for Closed, the only terminal state, and inspect the final outcome. A transmission failure after Dispatched can follow Dispatched → Failed → Closed with Outcome: Failed, without ever reaching Sent.

The diagram shows the main recipient-facing paths, rather than every possible backend transition. Channel feedback can be absent or arrive after link access. Refusal is offered on the hosted landing page after link access, without opening the content; a persisted Received milestone is not required. The TTL expiry arrow is one example: expiry closes any notice still open after processing, including one waiting for reading or commitment.

Key state transitions

Delivery of the notification and reading of the hosted notice are separate milestones. A Delivered notification provides delivery evidence for the channel; it does not prove that the recipient opened or read the hosted content.

Submitted → Processed — Namirial Notify validates the attachments, certifies the content, and prepares the notice for dispatch. An attachment rejected during this background processing causes Failed then Closed without dispatch or affidavit generation. A request rejected by submit-time validation never enters this lifecycle; see Step 5.

Processed → Dispatched → Sent — Processed means initial processing and content certification have completed. The platform then accepts responsibility for the communication and issues a notification send request, recorded as Dispatched. Sent is recorded when the selected sending channel reports successful transmission. Issuing the request does not guarantee transmission or delivery; an unsuccessful sending result can lead to Failed.

Sent → Delivered — A best-effort delivery signal is received for the notification. For email, signal availability depends on the recipient's mail server and mail client settings; for SMS, RCS, and WhatsApp, delivery feedback comes from the channel. Missing delivery feedback does not prove that the notification failed to arrive.

Link access → Received — The recipient follows the notification link and reaches the hosted landing page, before opening the content or completing any required authentication. This does not depend on a Delivered confirmation having been received. Received is specific to EviNotice — it does not exist in EviMail or EviSMS.

Received → Read — The recipient completes any required authentication and opens the notice content on the hosted page.

Read → Replied — If commitment is configured, the recipient accepts or rejects the notice. Unless EnforceTrackingUntilTimeToLive is enabled, the notice closes after the decision is recorded.

Landing page → Closed (Refused) — When AllowRefusal is enabled, the recipient can refuse after following the secure link, without opening the hosted content. The landing-page visit normally records Received before refusal. The events are processed asynchronously: ReceivedOn and the Received callback can be missing if refusal is processed first, and callback arrival order is not guaranteed. Refusal closes the notice; inspect the final Outcome in Closed. It is normally Refused, but an unrecovered failure takes precedence and can produce Outcome: Failed.

For API integrators: comparing lifecycle timestamps

The arrows describe logical milestones, not a guarantee that every *On timestamp is present or strictly increasing. ProcessedOn is populated after initial processing succeeds, but its value is the admission time recorded in SubmittedOn, so it does not measure processing duration; DispatchedOn marks the send request; SentOn uses the time reported by the successful sending result. Channel feedback and recipient actions are recorded independently, so link access can be recorded while delivery feedback is absent or pending. Do not treat equal timestamps or callback arrival order as a sequence number. Use Query or Get to reconcile the current state and final outcome, and inspect the event history when investigating timing.


Submit a certified notice

For API integrators. This section describes the Submit request. Web app users can follow the issuer guide.

POST /v2/EviNotice/Submit

Returns { "Id": "<uuid>" } on success. Note that Id is PascalCase, unlike the camelCase eviId returned by EviMail and EviSMS v1 endpoints.

Required fields

FieldDescription
SubjectSubject line of the certified notice. Shown to the recipient in the delivery notification.
BodyHTML content of the hosted notice. This is the certified content the recipient reads on the platform.
RecipientAddressRecipient's email address or mobile phone number in E.164 format. Determines the primary notification channel.

For Standard and Advanced notices, the API requires only Subject, Body, and RecipientAddress. Site and user WebDefaults prefill the WebUI send form; API submissions do not inherit those form preferences. Omitted API fields use their own defaults: Language and AffidavitLanguage default to en, and TimeToLive uses the platform's configured default. Set these fields explicitly when your integration requires specific values, so changes to WebUI preferences do not change its submissions. Account permissions and platform configuration still apply. See API defaults. QeRDS notices have additional mandatory conditions; see QeRDS recipient identity.

Useful fields you should configure

  • LookupKey — your own correlation key, filterable in Query. Maximum 35 characters. No uniqueness is enforced server-side — make it unique within your domain.
  • IssuerLegalName — the legal name of the sending organisation, recorded in the certification evidence.
  • RecipientDisplayName — the display name shown to the recipient in the delivery notification.
  • RecipientLegalName — the legal name of the recipient, recorded in the evidence.
  • CertificationLevel — the legal framework applied. Supported values include Standard, Advanced, QERDS, and regional variants such as Standard_EU, Advanced_EU, QERDS_ES, or QERDS_IT. Available levels depend on your account subscription — submitting an unsupported level returns 400. See Certification levels for the full list and QeRDS profile details.
  • TimeToLive — minutes the platform will attempt delivery and keep the notice accessible. Range: 60–86,400 (1 hour to 60 days). Uses the platform's configured default when omitted, independently of the WebUI send-form default.
  • Language — language for the delivery notification and hosted notice UI. Accepted values: ca, de, el, en, es, fr, it, pt, pt-BR, ro.
  • AffidavitLanguage — language for generated affidavit PDFs. Accepts the same values as Language.
  • NotificationLayout — visual layout of the hosted notice page: Certified (default, Namirial Notify branded) or AsIs (plain, without certification branding). EviMail exposes the same concept through DeliveryAppearance.
  • OnlineRetentionPeriod — number of years the notice and its evidence remain accessible online: 1 to 20 years; with by-submission billing your voucher tier can impose a lower maximum.
  • LandingPageInfoText — additional text shown on the landing page before the recipient opens the hosted content. Maximum 8,192 characters.

Notification channels

NotificationChannels controls which channels are used to alert the recipient. Supported values: SMS, WhatsApp, RCS, Email.

When RecipientAddress is an email address, Email is the default and the only accepted notification channel. For a mobile recipient, SMS is the default; NotificationChannels can select up to three enabled mobile channels (SMS, WhatsApp, RCS), without repeats. They are tried in order; the next channel is used only if the current one fails. WhatsApp and RCS require site enablement; WhatsApp also requires service enablement.

Recipient authentication

DeliverySignMethod controls how the recipient authenticates before accessing the hosted notice content.

ValueHow the recipient accesses the notice
WebClickNo authentication is required by the sign method itself. The recipient clicks the link and accesses the notice directly unless another step such as captcha or QeRDS legal-ID verification also applies. Lowest friction.
ChallengeA challenge question is shown before access. The recipient must provide the correct answer. Requires DeliverySignChallenge and DeliverySignChallengeResponse.
MobilePinA one-time PIN is sent via MobilePinChannels. The recipient enters the PIN to access the notice. Set DeliverySignFixedMobile if the PIN delivery number differs from RecipientAddress.
EmailPinA one-time PIN is sent to an email address. Set DeliverySignFixedEmail if the PIN delivery address differs from RecipientAddress.

Mobile PIN channels

MobilePinChannels configures PIN delivery attempts as an array of arrays. Supply it only with DeliverySignMethod: MobilePin. After null or empty groups are discarded, exactly three non-empty groups must remain, with no repeated channel within a group. The first PIN, sent when the recipient requests it, uses the first channel of the first group; no channel choice is offered. On a resend, the recipient chooses one channel from the next group (no choice is shown when that group has a single channel); after the third send, the last group is reused. NotificationChannels separately controls the original notice alert.

Supported channel values are SMS, WhatsApp and RCS. WhatsApp PIN delivery must be enabled both for the service and for the site; RCS must be enabled for the site. Confirm enablement before adding either channel.

With an explicit DeliverySignMethod: MobilePin, omitting MobilePinChannels defaults to three SMS attempt groups. The following request fragment makes that configuration explicit:

{
  "DeliverySignMethod": "MobilePin",
  "MobilePinChannels": [
    ["SMS"],
    ["SMS"],
    ["SMS"]
  ]
}

For QeRDS, the selected PIN method and fixed destination must also follow the ES/IT routing requirements.

Access after delivery

EvidenceAccessControlMethod controls access to the notice and its evidence once the recipient has accepted or rejected it, or it has closed. It is separate from the first-access DeliverySignMethod. Public allows anyone with the link, Challenge asks your question, and AutoChallenge asks for the recipient address. See evidence access control for the required fields and QeRDS rule.

QeRDS recipient identity

For a functional explanation of qualified delivery, see QeRDS with EviNotice. For API prerequisites and complete request examples, see Integrate QeRDS notices, including the qualified request fields.

For QeRDS-certified EviNotices, recipient legal-ID verification is required before the hosted notice is shown. QeRDS submissions also require the issuer account and site to be provisioned for the QeRDS API flow, including client-certificate authentication in addition to API credentials. For both ES and IT, the issuing account must be identity-verified with a QeRDS-eligible legal-document kind and have the identity-verification configuration for the selected variant. Send QeRDS API calls to the Namirial Notify API host for the environment, not to the customer's site host.

  • RecipientLegalIdRequired — must be true for QeRDS notices.
  • RecipientLegalIdKind / RecipientLegalIdValue — predefine the legal document type and value the recipient must confirm. Both are required for QERDS_IT; for QERDS_ES, supply both together or omit both so the recipient provides them.
  • QERDSEnrollmentAllowed — when true, recipients without a registered identity can complete enrollment during the same notice flow.
  • QERDSEnrollmentProfile — selects the site-configured enrollment profile for in-flow registration. Required when enrollment is enabled; a supplied profile must match the site configuration even when enrollment is disabled.
  • QERDSIdentityTenant — optionally selects the context for recipient identity lookup and in-notice enrollment. A supplied tenant must exactly match one configured on the site for the selected certification variant.
  • EvidenceAccessControlMethod — must be Public for qualified notices, whether submitted through Web or API.

For QERDS_ES, the delivery sign method must match the recipient address channel: email recipients use EmailPin and mobile recipients use MobilePin, with the fixed PIN destination matching RecipientAddress exactly. For API requests, use lowercase email addresses without surrounding spaces and identical E.164 mobile-number formatting; see the variant requirements.

For QERDS_IT, email recipients must use a mobile PIN destination (DeliverySignMethod: MobilePin plus DeliverySignFixedMobile), while mobile recipients must use an email PIN destination (DeliverySignMethod: EmailPin plus DeliverySignFixedEmail). RecipientLegalIdKind and RecipientLegalIdValue are required and must validate together.

If the recipient is not yet registered, the platform redirects them to the enrollment flow only when QERDSEnrollmentAllowed is enabled and the supplied QERDSEnrollmentProfile is configured on the site. Otherwise, access is blocked until the issuer resolves the identity requirement.

Commitment and refusal

CommitmentChoice controls whether the recipient can accept or reject the notice. Cannot be changed after submission.

ValueEffect
DisabledNo commitment action. The recipient reads the notice but cannot accept or reject.
AcceptThe recipient can only accept.
RejectThe recipient can only reject.
AcceptOrRejectThe recipient can accept or reject.

Additional commitment fields:

  • CommitmentCommentsAllowed — when true, the recipient can add a free-text comment with their decision.
  • AcceptReasons / RejectReasons — predefined reasons the recipient can select from. Both require CommitmentCommentsAllowed: true. AcceptReasons cannot be used with CommitmentChoice: Reject, and RejectReasons cannot be used with CommitmentChoice: Accept. Up to 20 reasons per list, each at most 150 characters, without HTML. Otherwise Submit returns 400.
  • RequireAcceptReason / RequireRejectReason — force the recipient to select or enter a reason before committing. When enabled, both require CommitmentCommentsAllowed: true. RequireAcceptReason cannot be used with CommitmentChoice: Reject, and RequireRejectReason cannot be used with CommitmentChoice: Accept; otherwise Submit returns 400.

For QeRDS notices sent through Web or API, keep comments disabled when acceptance is available (Accept or AcceptOrReject). To collect comments or rejection reasons, use CommitmentChoice: Reject with CommitmentCommentsAllowed: true. Do not configure acceptance reasons (AcceptReasons / RequireAcceptReason) for QeRDS acceptance.

EviMail exposes the same concept through a field named CommitmentOptions.

AllowRefusal is separate from commitment. When true, the recipient can refuse the notice without opening the hosted content after following the secure link. In standard non-QeRDS flows, refusal is presented on the landing step before the content is shown. Refusal closes the notice immediately, normally with outcome Refused, and generates a Refused affidavit if requested. An unrecovered failure takes precedence in the final outcome; inspect the final Outcome.

Affidavit configuration

AffidavitKinds selects which evidence events generate affidavits. Qualified notices require both SubmittedAdvanced and Read, or CompleteAdvanced, in this list; other kinds may be added. This applies to Web and API submission. For the full catalog and the lifecycle moment each kind is tied to, see Evidence and affidavits.

Callbacks

  • PushNotificationUrl — HTTP or HTTPS endpoint to receive state callbacks. Use HTTPS: over HTTP, Sent omits XmissionDetails and Replied omits Comments. Must be publicly reachable from Namirial Notify infrastructure.
  • PushNotificationFilter — state transitions that trigger a callback. Valid values: Processed, Dispatched, Sent, Delivered, Received, Read, Replied, Failed, Closed, AffidavitPublished. AffidavitPublished is a platform meta-event that fires when affidavit generation completes — it is not a lifecycle state. Received is unique to EviNotice.
  • PushNotificationExtraData — arbitrary string echoed back in every callback for this notice. Use it to embed a routing key or internal record ID so your callback handler can route the event without a separate lookup. Supply PushNotificationUrl and PushNotificationFilter together. PushNotificationExtraData (up to 1,024 characters) is allowed only when both are set; otherwise Submit returns 400.

Idempotency

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

Attachments

Include files in the hosted notice via the Attachments array. Data is required and is always base64-encoded in JSON. Supply MimeType, or a Filename whose extension lets the platform derive the MIME type. If MimeType is omitted, it is derived from the Filename extension.

For POST /v2/EviNotice/Submit, the current API accepts at most 14 attachments. Each file must be smaller than 8 MiB (8,388,608 bytes); the combined decoded file size must be at most 25 MiB (26,214,400 bytes). These are decoded-file validation limits, independent of WebUI defaults. The complete base64-encoded JSON request must also fit within the API host's request-size limit. A request approaching the combined decoded-file limit can be rejected before attachment validation.

Use ContentId to reference an attachment inline in the Body HTML using cid: syntax. Set IncludeOnAffidavits: true to include the attachment reference in generated affidavits. This requires a PDF attachment (MimeType application/pdf, supplied or derived from Filename), version 1.7 or earlier, that passes PDF validation, and a non-empty AffidavitKinds; otherwise Submit returns 400.

Reminders

Reminders re-send the notification email and are available only when RecipientAddress is an email address; a mobile recipient returns 400. They stop when the notice closes or after Max reminders; scheduling after the first reminder also stops when the next slot reaches Stop. Following the link does not stop them. Reading stops them only when it closes the notice (CommitmentChoice: Disabled without EnforceTrackingUntilTimeToLive). With a commitment choice, reminders continue after reading until the decision closes the notice; with EnforceTrackingUntilTimeToLive, they can continue after the decision until the notice closes. Configure them through Reminders:

FieldDescription
InitialISO 8601 duration after submission before the first reminder (for example P2D). Must not exceed TimeToLive. The first reminder ignores Days, TimeRange and Stop; keep Initial before Stop.
RepeatUse a whole-day ISO 8601 interval, for example P1D. Later reminders use the first allowed day/time window on or after the start of the day reached by adding this interval, in TimeZone; this is not an exact elapsed-time interval. Sub-day values are not supported in practice: the next reminder can be scheduled immediately, or in the next allowed window of the same day.
DaysAllowed days from the second reminder onward. Do not repeat a day.
TimeRangeAllowed windows from the second reminder onward: FROM08TO10, FROM10TO12, FROM12TO15, FROM15TO19, FROM19TO22 (19:00–22:00). Do not repeat a window.
MaxRequired, at least 1. For a TTL containing 1 whole day, at most 3; for 2–20 whole days, at most that number of days; above 20 days, at most 20. A TTL shorter than one day has no additional TTL-based cap.
StopISO 8601 duration from submission; later reminders at or after this point are not scheduled. It does not restrict the first reminder; keep Initial before Stop.
TimeZoneOne of Etc/GMT-14 through Etc/GMT+11; Etc/GMT0 is UTC. Region names such as Europe/Madrid return 400. The sign is inverted: Etc/GMT-1 means UTC+1.

What the recipient sees

The recipient's experience depends on the configured DeliverySignMethod.

WebClick

The recipient receives a notification (email, SMS, RCS, or WhatsApp) containing a secure link. Clicking the link opens the hosted notice page directly when no additional access step is configured. Appropriate for non-sensitive communications where you need evidence of delivery and access but not identity verification.

Challenge

After clicking the link, the recipient is presented with a challenge question configured in DeliverySignChallenge. They must provide the correct answer (configured in DeliverySignChallengeResponse) before the notice content is revealed. Use when you need to confirm the recipient's identity using information only they would know — a contract reference, last four digits of a document, or similar.

MobilePin

After clicking the link, the recipient is prompted to enter a one-time PIN delivered to their mobile device via the channels configured in MobilePinChannels. If the mobile number for PIN delivery differs from RecipientAddress, configure it in DeliverySignFixedMobile. Each element of MobilePinChannels lists the channels offered for one PIN send. The first PIN, sent when the recipient requests it, uses the first channel of the first group; no channel choice is offered. On a resend, the recipient chooses one channel from the next group (no choice is shown when that group has a single channel); after the third send, the last group is reused.

EmailPin

After clicking the link, the recipient is prompted to enter a one-time PIN sent to an email address. If the PIN delivery address differs from RecipientAddress, configure it in DeliverySignFixedEmail.

Captcha and QeRDS-specific checks

Depending on tenant configuration, the recipient can also encounter a captcha step before the content is displayed.

For QeRDS-certified notices, a verified recipient identity is required. The recipient is asked to provide or confirm the required identity details when needed for the notice, before the applicable content-access checks. If no verified identity is already registered and in-flow enrollment is enabled, the recipient is redirected to the identity provider and then returned to the notice.

Commitment actions on the hosted page

When CommitmentChoice is not Disabled, the hosted notice page displays the configured action buttons after the recipient has opened the content. If CommitmentCommentsAllowed is true, a comment field is shown alongside the buttons. If AcceptReasons or RejectReasons are configured, the recipient selects from those predefined options rather than typing freely. CommitmentChoiceButtonOnly is allowed only with CommitmentChoice: Accept or Reject. It replaces the standard action label with CommitmentChoiceButtonText (or the default Finish label); it does not hide the comment field. CommitmentChoiceButtonText accepts at most 15 unaccented letters (A–Z, a–z) or digits, with no spaces or punctuation.


Callbacks and what you receive

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

When a state in PushNotificationFilter is reached, Namirial Notify sends an HTTP POST to PushNotificationUrl with the following JSON payload.

Base payload

FieldTypeDescription
IdentifierstringID of this callback, retained across retries. Use it to detect repeated deliveries of the same callback.
KindstringThe state or event that triggered this callback (e.g. Sent, Delivered, Received, Read, Replied, Closed, AffidavitPublished).
DatedatetimeTimestamp of the state transition that fired this callback.
EvidenceIdUUIDThe Id of the EviNotice, as returned at submission.
EvidenceTypestringAlways eviNotice for EviNotice 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 submitting account.
AdditionalDataobjectCommon and event-specific fields described below.

AdditionalData fields — always present

FieldDescription
SubjectThe subject of the notice.
LookupKeyThe integrator-assigned lookup key set at submission.
StateCurrent lifecycle state.
CreationDateTimestamp when the notice was submitted.
FromEmail address of the issuing account (same as OwnerEmail), rather than the notification sender address.
ToRecipient address the notification was sent to.

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
RepliedKind — Accepted or Rejected; Comments — comment or selected reason (HTTPS only). Actor fields are included when available.
ClosedOutcome — the final outcome (Accepted, Rejected, Refused, Failed, etc.). OutcomeDescription — human-readable description of the outcome.
AffidavitPublishedAffidavitId, AffidavitKind (response identifier), AffidavitName; RequestId for on-demand requests and Regenerated: true when regenerated. See the identifier mapping.

See callback extra fields for Dispatched, Sent, Delivered, Received, Read and Failed, including progress, actor fields and HTTPS-only fields.

Callback reliability

This guidance applies to the application receiving callbacks:

  1. Avoid processing the same callback twice. A retry uses the same Identifier. Store it with the event and ensure that a duplicate does not repeat a business action, such as creating a follow-up task. Different events for the same notice have different identifiers.
  2. Confirm receipt promptly. After validating and durably storing or queueing the event, return an HTTP success response such as 200 OK. Perform slower work afterwards. Errors or timeouts can cause the platform to retry, even if your application received the first request.
  3. Connect the callback to your records. Set PushNotificationExtraData to an internal reference, such as order-12345, in the Submit request. It is returned as AdditionalData.ExtraData, allowing your application to find that order without a separate lookup through the API. This reference does not authenticate the callback.

See Handling callbacks reliably for duplicate handling, acknowledgement, and correlation examples.

Securing your callback endpoint

For integrators receiving callbacks. These controls apply to incoming requests to your application.

See Security and authentication for the supported callback model and compensating controls. The documented model does not define signed callback verification or a stable source-IP allowlist.


States reference

StateDescription
DraftNotice has been staged but not yet submitted.
SubmittedNotice has been accepted by the platform.
ProcessedAttachments validated, content certified, notice ready for dispatch.
DispatchedThe platform completed its initial checks, accepted responsibility for the communication and issued the notification send request; successful transmission has not yet been confirmed.
SentThe selected sending channel reported successful transmission of the notification.
DeliveredA best-effort delivery signal was received for the notification; this does not establish that the hosted content was opened.
ReceivedRecipient followed the hosted notice link. The recipient has not yet read the content. Unique to EviNotice.
ReadRecipient opened and read the hosted notice content.
RepliedRecipient accepted or rejected the notice.
ClosedNotice lifecycle is complete; callbacks for requested affidavits can still arrive afterwards.
FailedA processing, transmission or delivery failure occurred. It is not final by itself: wait for Closed and inspect Outcome. Initial processing failures close immediately; other failures can recover while the notice remains open.

On Replied: by default, the notice closes immediately after the commitment is recorded. Some configurations keep tracking open until the TTL elapses. Subscribe to both Replied and Closed if you need to react to the recipient's answer and then mark the lifecycle as final.

On Received vs Read: Received fires when the recipient clicks the link; Read fires when they open the content. A recipient can click the link and abandon the page without reading — both events are recorded independently.

On refusal: the recipient follows the link to the landing page and refuses without opening the content. Refusal closes the notice, normally with outcome Refused; an unrecovered failure takes precedence. Refused is an outcome, rather than a separate lifecycle state.


Evidence and affidavits

AffidavitKinds selects which evidence events generate signed affidavit PDFs. Generation is asynchronous; you receive an AffidavitPublished callback when each affidavit is ready (if AffidavitPublished is in PushNotificationFilter).

When each affidavit is generated

AffidavitKinds valueTriggers atNotes
SubmittedProcessedCertifies the notice content at submission time.
SubmittedAdvancedProcessedAdvanced variant with extended content certification.
DispatchedDispatchedCertifies that the notification send request was issued (email recipients only).
TransmissionResultTransmission result (Sent or NotSent event)Certifies successful transmission or transmission failure. NotSent is a history event, not a lifecycle state or callback filter value.
DeliveryResultDelivery result (Delivered or Undelivered event)Certifies successful delivery or delivery failure. Undelivered is a history event, not a lifecycle state or callback filter value.
ReceivedReceivedCertifies that the recipient followed the hosted notice link.
ReadReadCertifies that the recipient opened and read the hosted notice content.
CommittedRepliedCertifies the recipient's acceptance or rejection decision.
CommittedAdvancedRepliedAdvanced variant of the commitment affidavit.
RefusedClosed (outcome Refused)Certifies that the recipient refused the notice without opening it.
ClosedClosure eventCertifies closure when a closure event is recorded; not every transition to Closed generates this affidavit.
ClosedAdvancedClosure eventAdvanced variant of the closure affidavit, subject to the same condition.
CompleteClosedCertifies the full chain from submission to closure (only generated when the notice was processed).
CompleteAdvancedClosedAdvanced variant of the complete lifecycle affidavit.
EventVarious technical eventsInternal technical record for events without a more specific affidavit kind.
OnDemandOn requestRequires a separate POST /v2/EviNotice/Affidavits/Request call while the notice is still eligible.
ContentDownloadAttachment downloadCertifies that the recipient downloaded an individual attachment or a ZIP containing attachments. Use it together with EnforceTrackingUntilTimeToLive: true. Enabling either option without the other returns 400. See by-submission voucher eligibility.

A failure before processing completes, such as a PDF rejected during background attachment validation, closes the notice without generating affidavits, even if Submitted, Closed, or Complete was requested. This avoids generating certificates for notices that could not be processed. For later transmission or delivery failures, the corresponding result affidavit can certify the negative result when requested. Failed remains a value in the API contract, but the notice lifecycle does not generate a separate Failed affidavit. Use status, failure details, and callbacks to diagnose an early failure.

For the legal implications and cross-service comparison of each affidavit type, see Evidence and affidavits.


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, for point-in-time snapshots, or for batch reconciliation.

POST /v2/EviNotice/Query

EviNotice Query uses cursor-based pagination, unlike the offset-based pagination in EviMail and EviSMS. Pass Cursor from the previous response to retrieve the next page. When Cursor is absent from the response, there are no further results.

Response field names are PascalCase (Cursor, Results) rather than the camelCase used by EviMail and EviSMS v1 query endpoints. Deserialise accordingly if sharing response models across services.

Common filters:

  • LookupKeys: ["your-key"] — fetch by your correlation key.
  • State: "Closed" — fetch only closed notices.
  • Outcome: "Received" — find closed notices whose final recorded outcome is access to the hosted notice link. Use ReadOn to check whether opening the content was recorded.
  • Limit — maximum results per page (1–100, default 100).

To retrieve affidavit or attachment metadata, use the Get endpoint (GET /v2/EviNotice/{Id}) with IncludeAffidavits=true or IncludeAttachments=true. To download all affidavits or attachments as a ZIP file, use the dedicated download endpoints.


First-call walkthrough

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

What you need

  • Namirial Notify credentials, set as EVI_USER and EVI_PASS
  • A UUID for the submission's idempotency token, set as EVI_IDEMPOTENCY_TOKEN
  • A recipient email address or mobile number for testing
  • A dedicated non-production HTTPS endpoint that you control for callbacks; use synthetic data and follow the callback testing guidance

Step 1 — Submit your first notice

Use a fresh idempotency token for each new submission. Reuse the same value only when retrying that submission.

curl -X POST "https://api.evicertia.com/v2/EviNotice/Submit" \
  -u "$EVI_USER:$EVI_PASS" \
  -H "Content-Type: application/json" \
  -H "X-Evi-IdempotencyToken: $EVI_IDEMPOTENCY_TOKEN" \
  -d '{
    "Subject": "Test certified notice",
    "Body": "<p>This is a test certified notice. Please read and acknowledge.</p>",
    "RecipientAddress": "recipient@example.com",
    "LookupKey": "test-001",
    "CertificationLevel": "Standard_EU",
    "DeliverySignMethod": "WebClick",
    "NotificationLayout": "Certified",
    "Language": "en",
    "AffidavitKinds": ["Submitted", "DeliveryResult", "Read", "Closed"],
    "PushNotificationUrl": "https://your-endpoint.example.com/callbacks",
    "PushNotificationFilter": ["Sent", "Delivered", "Received", "Read", "Failed", "Closed", "AffidavitPublished"]
  }'

A 200 OK response contains { "Id": "<uuid>" }. Store the Id — you will use it to poll status and retrieve evidence.

Step 2 — Verify the notice progresses

Query by LookupKey to confirm the notice moves through Submitted → Processed → Dispatched → Sent:

curl -X POST "https://api.evicertia.com/v2/EviNotice/Query" \
  -u "$EVI_USER:$EVI_PASS" \
  -H "Content-Type: application/json" \
  -d '{"LookupKeys":["test-001"]}'

Or retrieve it directly:

curl "https://api.evicertia.com/v2/EviNotice/<Id>" \
  -u "$EVI_USER:$EVI_PASS"

Step 3 — Follow the notice as the recipient

Open the delivery email in the recipient's inbox, click the secure link, and read the notice. Verify that:

  • A Received callback fires when the link is clicked
  • A Read callback fires when the notice is opened
  • The notice state in Query advances to Read

Step 4 — Confirm closure and download the affidavit

After the notice closes, retrieve the affidavit:

curl "https://api.evicertia.com/v2/EviNotice/<Id>/Affidavits" \
  -u "$EVI_USER:$EVI_PASS" \
  --output evinotice-affidavits.zip

This returns a ZIP file containing all generated affidavit PDFs. Verify the affidavit content covers the lifecycle events you configured in AffidavitKinds.

Step 5 — Test the failure path

Test submission rejection and background failure separately in a test environment:

  1. Submit-time rejection: send a malformed PDF with IncludeOnAffidavits: true. A PDF rejected by the submission validator returns 400 Bad Request; no notice is created and no notice callbacks or affidavits are generated.
  2. Background failure: PDF inspection is a platform-side check configured for each environment. Ask your Namirial contact to confirm it is active in your test environment and provide a fixture (PDF 1.7 or earlier) confirmed to pass submission but fail background inspection, for example a password-protected PDF. This check cannot be enabled through the Submit request. If inspection is disabled, the fixture will not exercise this rejection path and may process normally. Set IncludeOnAffidavits: true, retain the requested AffidavitKinds from Step 1, and use a fresh idempotency token. Confirm that submission succeeds and returns an Id before waiting for callbacks. An immediate 400, including rejection of a PDF version newer than 1.7, tests submission rejection instead.

For the background failure, confirm that:

  • The notice reaches Failed then Closed with Outcome: Failed
  • A Failed callback fires to your endpoint (Failed must be in PushNotificationFilter, as in Step 1)
  • The Closed callback includes Outcome: Failed in AdditionalData
  • No affidavits are generated because the notice failed before processing completed

Integration checklist

  • Set LookupKey on every Submit and persist Id from the response.
  • Send X-Evi-IdempotencyToken (UUIDv4) on every Submit. Treat 202 Accepted as success.
  • Choose DeliverySignMethod deliberately — WebClick for low-friction; MobilePin or Challenge for sensitive content.
  • Subscribe only to the callback kinds you act on. Received and Read are unique to EviNotice — include them if your flow depends on distinguishing link-click from content-open.
  • Make your callback handler idempotent, keyed on Identifier.
  • Store the raw callback body before parsing.
  • Include AffidavitPublished in PushNotificationFilter if you download affidavits programmatically — it tells you exactly when each affidavit is ready.
  • If using CommitmentChoice, test both the accept and reject paths in pre-production.
  • If using AllowRefusal, subscribe to Closed with outcome Refused and handle it as a terminal negative result.
  • Include OnDemand in AffidavitKinds at submit time if you plan to call the affidavit request endpoint later — this cannot be added retroactively.
  • Remember that EviNotice query responses use PascalCase field names (Cursor, Results, Id) — deserialise separately from EviMail/EviSMS if sharing models.
  • Use the GET /v2/EviNotice/{Id}/Affidavits endpoint to download affidavit ZIPs rather than requesting them one at a time.

Troubleshooting

The table below covers API integration issues. For Web app issues, see the EviNotice issuer guide.

SymptomLikely causesWhat to checkWhat to do
No callbacks receivedPushNotificationUrl or PushNotificationFilter missing; expected Kind absent from filter; endpoint returned non-2xx or retries exhaustedQuery state and check callback/server logsConfirm URL/filter; use polling as fallback
Comments or XmissionDetails missingCallback URL uses HTTPCheck PushNotificationUrlUse HTTPS to receive these fields
Notice stays in Dispatched or SentNotification channel slow or unavailable; recipient MTA greylisting (email); SMS operator delayTimestamps in Query response: DispatchedOn, SentOn, DeliveredOnWait; do not resubmit
Recipient says they did not get the notificationSpam filter caught the email; wrong address or number; SMS delivery failureDelivered callback and DeliveredOn timestamp; TransmissionResult affidavit if generatedConfirm address; check spam folder; resubmit with corrected address and a new idempotency token
Received callback fired but Read never firesRecipient clicked the link but abandoned the page without opening the contentReceivedOn timestamp present; ReadOn absent in QueryNormal — Received and Read are independent events; wait for TTL or contact the recipient
Notice closed with Outcome: FailedA permanent processing or transmission failure was recorded before closureFailedOn, callback payloads, and failure detailsCorrect the payload or address; resubmit with a new idempotency token only after the cause is fixed
Commitment callback not receivedCommitmentChoice is Disabled; Replied not in PushNotificationFilterSubmit request at creation timeCannot change CommitmentChoice after submission; resubmit with the correct setting and a new idempotency token
Affidavit not availableGeneration is asynchronous; AffidavitPublished has not fired yet; the relevant kind was not included in AffidavitKinds at submissionQuery with IncludeAffidavits=true; check AffidavitKinds on the Get responseWait for AffidavitPublished callback; if the kind is missing, it cannot be added retroactively — resubmit
Submit → 400 Bad RequestMissing required field (Subject, Body, or RecipientAddress); invalid CertificationLevel for your account; attachment too large or count exceeded; a field combination that breaks a documented field ruleProblem+JSON body: Detail and InvalidValuesFix the flagged field; retry with a new idempotency token
Submit → 401 UnauthorizedWrong environment base URL; credentials rotatedAuthorization header; confirm target environmentRe-issue credentials through your Namirial Notify contact
Submit → 403 ForbiddenAccount not provisioned for EviNotice; insufficient credit balanceAccount permissions and credit balanceContact your Namirial Notify account manager