# Performance and scaling

Performance-related guidance derived from the Namirial Notify API references.

The API references do not publish explicit throughput limits, concurrency
ceilings, or rate-limit headers. Design your
integration conservatively and validate expected traffic with your Namirial
Notify contact before go-live.

## Prefer callbacks over frequent polling

Callbacks are the most efficient way to follow transaction progress.

- Use `PushNotificationUrl` and `PushNotificationFilter` for near-real-time
tracking.
- Reserve Query and Get operations for reconciliation, scheduled audits, and
recovery when callbacks were missed or delayed.
- Make callback processing idempotent so retries do not create duplicate
internal updates.


See [Callbacks and webhooks](/products/namirialnotify/dev/callbacks) for retry behavior.

## Query efficiently

When querying large result sets:

- Filter by `WithUniqueIds`, `WithLookupKeys`, state, or outcome whenever
possible.
- Use `Limit` and `Offset` for EviMail, EviSMS, and EviPost.
- Use `Limit` and `Cursor` for EviNotice.
- Avoid broad unfiltered reconciliation jobs if you already know the specific
IDs or lookup keys you need.


## Retrieve large payloads only when needed

Metadata-heavy responses are useful, but more expensive than plain status queries.

- **EviMail, EviSMS, and EviPost:** Request `IncludeAffidavits` / `IncludeAttachments`
(`IncludeAffidavitsOnResult` for EviPost) only when your process actually needs the
metadata. EviPost has no attachment include flag.
- **EviNotice:** Use `IncludeAffidavits` and `IncludeAttachments` on the Get endpoint
for metadata. To retrieve file content, use the dedicated ZIP download endpoints
(`/Affidavits`, `/Attachments`) only when your process actually needs the files.
- Separate status-tracking jobs from file-download jobs in your integration.


## Protect submit operations from duplication

- Include `X-Evi-IdempotencyToken` on Submit requests across all services (EviMail, EviSMS, EviNotice, EviPost).
- For all services, use your own `LookupKey` strategy so retries and support
workflows can be correlated safely.
- Do not retry a failed submit blindly if you cannot determine whether the
upstream system already accepted it.


## Bulk and campaign planning

EviNotice, EviMail, and EviSMS all expose a dedicated **batch API** for sending the same
certified communication to many recipients as a single managed job. See the service
reference pages for the full workflow and CSV recipient format:
[EviNotice batch](/products/namirialnotify/apis/evinotice-api#batch-operations),
[EviMail batch](/products/namirialnotify/apis/evimail-api#batch-operations),
[EviSMS batch](/products/namirialnotify/apis/evisms-api#batch-operations).

For planning a batch campaign:

- Use the batch API rather than repeated single-submit calls — it provides progress
tracking (`SentCount`, `FailedCount`, `ProgressPercentage`) and a managed lifecycle.
- Upload recipients as a single `text/csv` file, then query the batch or recipient list
to review the imported totals before starting processing.
- Configure `PushNotificationUrl` or `BatchPushNotificationUrl` on the batch when
generated evidences should send the normal per-evidence callbacks. Track the
batch lifecycle itself by polling the batch resource.
- Use `ScheduledDate` to spread load and coordinate expected campaign size and traffic
profile before production launch.
- Use pre-production to validate request construction and lifecycle handling before
increasing load.


Because no portal-wide rate-limit policy is documented, do not assume that
aggressive parallelism or tight retry loops are safe.

## Evidence retrieval strategy

Affidavits, attachments, and original documents can be significantly larger than
status-only responses.

- Fetch evidence when a downstream business step needs it.
- Cache the fact that evidence was already retrieved.
- Avoid downloading the same blobs repeatedly during reconciliation jobs.
- For EviPost on-demand affidavits, treat generation and pickup as a separate
asynchronous process.


## Pre-production validation checklist

- Confirm expected traffic profile and peak volume assumptions.
- Test callback handling under retries and delayed delivery.
- Measure the cost of metadata-only queries versus blob-heavy retrieval.
- Confirm how and when affidavits should be fetched in the target business
process.
- Validate operational dashboards and alerting before switching to production.


## Related

- [Integration workflows](/products/namirialnotify/dev/integration-patterns)
- [Callbacks and webhooks](/products/namirialnotify/dev/callbacks)
- [Security and authentication](/products/namirialnotify/dev/security-best-practices)
- [API reference overview](/products/namirialnotify/apis/overview)