Common end-to-end patterns that repeat across the Namirial Notify APIs.
Use it together with the service reference pages when you are designing a production integration.
Regardless of service, the recommended lifecycle is:
- Submit the transaction and store the returned identifier.
- Store your own correlation key, typically
LookupKey. - Configure callbacks when you need near-real-time status updates.
- Use Query or Get operations to reconcile state and retrieve evidence.
- Download or request affidavit content only when your workflow needs it.
| Step | What to persist in your system |
|---|---|
| Submit | Request timestamp, environment, service, returned transaction ID |
| Correlation | LookupKey and any internal business identifier |
| Tracking | Last known state, outcome, callback event identifiers |
| Evidence retrieval | Affidavit IDs, attachment IDs, download timestamps |
Use this pattern when the certified content is the delivered message itself.
- Submit the message with
POST /v1/EviMail/SubmitorPOST /v1/EviSms/Submit. IncludeX-Evi-IdempotencyTokento protect against duplicate submissions when your client retries. To receive callbacks, includePushNotificationUrland a nonemptyPushNotificationFilteron Submit. SetPushNotificationExtraDataif you need a correlation value. - Persist the returned
eviId. - Process callbacks as they arrive.
- Reconcile with
GET /v1/EviMail/QueryorGET /v1/EviSms/QueryusingWithUniqueIdsorWithLookupKeys. - Request affidavit metadata only when needed with
IncludeAffidavits=true. For EviMail and EviSMS, also sendIncludeAffidavitBlobs=falseexplicitly. - Pass the affidavit IDs from Query or
AffidavitPublishedcallbacks toPOST /AffidavitsDownloadto retrieve the signed PDFs in a ZIP archive. - For EviMail on-demand affidavits: if the original submit included
AffidavitKinds: [OnDemand], request a custom affidavit withPOST /v1/EviMail/AffidavitRequest.
- Use callbacks as the primary signal for progress.
- Use Query as a reconciliation step, a recovery path, or a scheduled audit.
- Avoid requesting affidavit or attachment metadata on every poll.
- Treat EviMail on-demand affidavits as a separate asynchronous workflow from normal state tracking.
For qualified notices, use this lifecycle pattern together with Integrate QeRDS notices. Qualified submission adds certificate authentication and mandatory recipient-identification prerequisites.
Use this pattern when the certified content is hosted on the platform and the recipient interacts with that hosted notice.
- Submit the notice with
POST /v2/EviNotice/Submit. IncludeX-Evi-IdempotencyTokento protect against duplicate submissions when your client retries. - Persist the returned
Id. - Configure callback fields if you need asynchronous updates.
- Process notice callbacks such as
Processed,Delivered,Received,Read,Replied, andClosed. - Retrieve the current record with
GET /v2/EviNotice/{Id}when you need the latest full object. - Use
IncludeAffidavitsorIncludeAttachmentson the Get endpoint for metadata-driven retrieval. - Download ZIP archives from
/Affidavitsor/Attachmentsonly when your process actually needs the files.
The legacy /api/v2/... form is still accepted for backward compatibility. For new integrations, use the /v2/... routes shown here.
When reconciling many notices, use POST /v2/EviNotice/Query with Limit and Cursor rather than repeatedly fetching single notices.
Use this pattern when physical postal delivery is part of the certified process.
- Submit with
POST /v1/EviPost/Submit. - Include
X-Evi-IdempotencyTokento protect against duplicate submits when your client retries. - Persist the returned
uniqueId. - Configure
PushNotificationUrlandPushNotificationFilterwhen you need asynchronous state tracking. Supply both fields and use each filter value once. - Reconcile with
GET /v1/EviPost/Query. SendIncludeAffidavitBlobsOnResult=falsefor metadata only. - If you need a custom affidavit after submission, call
POST /v1/EviPost/AffidavitRequestfor an openLetterorLetterLite. Configure the advanced profile and on-demand flag at Submit. See eligibility and limits. A200 OKconfirms queueing. Use Query to check which affidavits were generated. - When the affidavit is ready, the platform fires an
AffidavitPublishedcallback to thePushNotificationUrlconfigured at submission, providedAffidavitPublishedis included inPushNotificationFilter. - Pass
AdditionalData.AffidavitId, or an affidavit ID returned by Query, toPOST /AffidavitsDownloadto retrieve the signed PDF in a ZIP archive.
- Treat on-demand affidavit generation as a separate asynchronous workflow.
- Keep the main delivery lifecycle and the affidavit-request lifecycle as two distinct processes in your integration.
Use this pattern when you need to send the same certified communication to many recipients as a single managed job.
- Create an empty batch with
POST /v2/Evi{Service}/Batches. You receive aBatchId. - Set the content — for EviNotice and EviMail, upload the HTML body with
PUT .../Body; for EviSMS, set theTextfield viaPATCH. - Upload recipients with
POST .../Recipientsas atext/csvfile. - Optionally add attachments with
POST .../Attachments(EviNotice and EviMail only). - Configure per-message options (
PATCH .../{BatchId}) — certification level, callbacks, scheduling, etc. - For EviMail and EviSMS, submit the batch via
PATCHwithState: Submittedand a futureScheduledDatein UTC. For EviNotice, follow the batch reference below. - Poll
GET .../{BatchId}to follow progress (SentCount,FailedCount,ProgressPercentage).
See the service reference pages for the CSV column format and the full option set: EviNotice batch, EviMail batch, EviSMS batch.
The batch API is under the v2 base path (/v2/Evi{Service}/Batches), even for EviMail and EviSMS whose single-send operations use /v1.
Across EviNotice, EviMail, EviSMS, and EviPost:
- Prefer callbacks for near-real-time updates.
- Use Query or Get endpoints for reconciliation, backfilling, and auditing.
- Make callback handling idempotent, because retries can happen if your endpoint is unavailable or slow.
- Do not assume callbacks arrive in lifecycle order. Deduplicate by
EvidenceType,EvidenceId,Kind, andIdentifier, useDateas the event time, and reconcile with Query or Get.
See Callbacks and webhooks for payload examples and retry behavior.
If your integration cannot receive callbacks, you can track status by polling the Query or Get endpoints. Interpret the results using the timestamp fields rather than the live State or Outcome. State changes as the transaction advances, while Outcome may remain None until closure. Neither should be treated as the final result until State is Closed; at that point, Outcome is final. See State, outcome, and timestamp fields for the full model.
- A 4xx response means the request was rejected and the transaction never entered the system. The error body lists the reasons. For EviNotice,
409is an exception: another request with the same idempotency token is still running and may create the notice; retry with the same token. - A 20x response means the request was accepted. The transaction is created and processed asynchronously in the background. The applicable submission timestamp (
NewOnorSubmittedOn) is set first, followed byReadyOnorProcessedOn, thenDispatchedOn, and later milestones as processing advances.
A successful 20x does not guarantee final success. After acceptance, the transaction can still fail during asynchronous processing — for example, an EviNotice with a PDF attachment marked IncludeOnAffidavits: true that passes submit validation but fails background inspection (such as a password-protected PDF, when inspection is enabled) is accepted first and later closes with Outcome: Failed. With IncludeOnAffidavits: true, a malformed PDF is rejected at submit with 400. Early failures generate no affidavits; inspect the web history for the failure.
Map your business flags to timestamp fields:
| Flag | Field to check |
|---|---|
| Processed and certified by the platform | ReadyOn is present (ProcessedOn for EviNotice) |
| Handed to the sending process or channel | DispatchedOn is present |
| Accepted by the recipient's server / operator | SentOn is present |
| Delivered | DeliveredOn is present |
| Read | ReadOn is present. For EviSMS, read tracking requires RCS delivery; plain SMS cannot report reads. |
| Attachment downloaded (EviNotice) | The ContentDownload affidavit is present for an individual attachment or a ZIP containing attachments (request it at submit time). The API exposes no download timestamp. |
Transmission diagnostics
Where exposed, XmissionResult and XmissionSummary provide the recorded transmission result and human-readable diagnostic details. These fields can be updated as sending attempts are processed. Do not parse XmissionSummary or use either field as a lifecycle state. Derive business flags from the milestone timestamps, and use the final Outcome after the state becomes Closed.
- Submit and store the returned ID and your
LookupKey. - Poll Query or Get on a backoff interval until
StateisClosed. - On each poll, update your flags from the timestamp fields.
- When
StateisClosed, read the finalOutcomeand stop polling. - For EviNotice, EviMail, and EviSMS, keep polling within the transaction's
TimeToLivewindow; once it elapses the state moves toClosedand no further timestamps will appear. For EviPost, the tracking window depends on the service type. Check the recorded outcome; the window ending does not guarantee closure.
Use a backoff interval rather than tight polling, and reconcile in batches where the endpoint supports it. The public API references do not define a cross-service rate-limit contract; confirm expected traffic with your Namirial Notify contact before go-live.
- Store the service-specific transaction ID returned by Submit.
- Store your own stable
LookupKeyso you can correlate business events. - Separate operational status tracking from large file retrieval.
- Design callback processing to be idempotent.
- Reconcile state periodically, even when callbacks are enabled.
- Download affidavit blobs, attachment blobs, or ZIP archives only in the steps that require them.