# API reference overview

Namirial Notify provides REST APIs for sending certified communications and
retrieving related evidence. Service APIs let you submit messages or notices,
query their status, and receive real-time callbacks when their state changes.

## Available APIs

| API | Service | Use case | Version |
|  --- | --- | --- | --- |
| **[EviMail API](/products/namirialnotify/apis/evimail-api)** | Certified email | Send individual emails or batches with proof of delivery and read receipts | v1 (single-message), v2 (batch) |
| **[EviNotice API](/products/namirialnotify/apis/evinotice-api)** | Hosted notices | Send individual notices or batches with hosted content, digital signatures, and commitment tracking | v2 |
| **[EviSMS API](/products/namirialnotify/apis/evisms-api)** | SMS & RCS | Send certified SMS messages or SMS batches; single-message submissions also support RCS | v1 (single-message), v2 (batch) |
| **[EviPost API](/products/namirialnotify/apis/evipost-api)** | Physical postal | Send certified physical postal communications (burofax equivalent) with delivery tracking | v1 |
| **[Shared download APIs](/products/namirialnotify/apis/downloads-api)** | Affidavits and attachments | Download affidavit PDFs or attachment content when you already have their IDs | v1 |


Each reference page includes:

- Complete endpoint descriptions with request/response examples
- Key request and response fields
- State and outcome tables
- Links to the full OpenAPI 3.0.3 specification


Use the unified [Namirial Notify OpenAPI](/products/namirialnotify/apis/oas/namirialnotify-api) page to browse all documented service endpoints in one place.

EviMail, EviNotice, and EviSMS each include their single-message and batch operations under one service entry. For batch workflows and options, see the batch sections in the [EviMail reference](/products/namirialnotify/apis/evimail-api#batch-operations), [EviNotice reference](/products/namirialnotify/apis/evinotice-api#batch-operations), and [EviSMS reference](/products/namirialnotify/apis/evisms-api#batch-operations).

## Common patterns

Service APIs share these fundamental patterns:

- **Submit** — POST a message with metadata, recipients, options, and optional attachments. Returns a unique ID.
- **Query** — GET or POST to retrieve the status of one or many submitted messages, filtered by ID, state, outcome, or lookup key.
- **Callbacks** — Configure `PushNotificationUrl` and `PushNotificationFilter` to receive real-time webhooks when messages change state.
- **States & outcomes** — Submitted messages move through a service-specific lifecycle, with `Closed` as the terminal state. Intermediate milestones such as `Sent` or `Delivered` appear only when the corresponding event is recorded; at closure, `Outcome` reports the final result.
- **Affidavits** — Request signed evidence PDFs for key events. Callbacks and
metadata-only query modes expose affidavit identifiers; download endpoints
return the PDF files. Deprecated v1 query options can still embed PDF bytes
for one result, but are not recommended for new integrations.


## Getting started

### Authentication

All APIs require **HTTP Basic authentication**. Include your Namirial Notify credentials (username and password) in the `Authorization` header:


```
Authorization: Basic <base64(username:password)>
```

Contact your Namirial Notify account manager if you don't have credentials yet.
API access is provisioned per service. If valid credentials return `403 Forbidden`,
contact your account manager to confirm that the required service permission is enabled.

### Environments

Test in pre-production before switching to production:

| Environment | Base URL | Use |
|  --- | --- | --- |
| **Production** | `https://api.evicertia.com` | Live certified communications |
| **Pre-production / QA** | `https://api.ecertia.com` | Testing and integration |


For the public Namirial Notify API environments, single-message operations for EviMail, EviSMS, and EviPost use the `/v1` base path. EviMail and EviSMS batch operations use `/v2/EviMail/Batches` and `/v2/EviSms/Batches`, respectively.
Use public routes such as `/v1/EviMail/Submit`, `/v1/EviSms/Submit`, and `/v1/EviPost/Submit`. Shared download source contracts expose root routes such as `/AffidavitsDownload` and `/AttachmentDownload`; use the route style shown in the relevant reference page for that API.
EviNotice uses the `/v2/` path prefix. The legacy `/api/v2/...` form is still accepted for backward compatibility.
Some lower-level technical artifacts may show V1 routes without the `/v1` prefix. For customer integrations, use the public paths shown in this documentation.

### Request and response format

All APIs accept **JSON** for requests and return **JSON** for most responses. The exceptions include affidavit download endpoints, which return PDF files or ZIP packages, and EviNotice attachment downloads, which return binary files or ZIP packages. Timestamps are ISO 8601 format. Large payloads (query results) may be paginated using `Limit` and `Offset` (EviMail, EviSMS, EviPost) or cursors (EviNotice).

### Online retention and LTA storage

`OnlineRetentionPeriod` and `LtaStorage` control separate parts of evidence
custody. `OnlineRetentionPeriod` specifies how many years the evidence remains
accessible through Namirial Notify. When `LtaStorage` is `true`, the platform
stores the transaction bundle in Namirial Archive during post-close processing,
after the individual transaction reaches `Closed`; it does not wait for the
online retention period to expire. The site must have LTA enabled.

For batch APIs, the LTA option is propagated to each transaction generated from
the batch. Each generated transaction is stored after its own tracking closes;
the batch itself has no separate LTA lifecycle.

The documented callback filters do not include an LTA-completion event. Do not
treat a `Closed` callback as proof that the post-close LTA step finished. In the
transaction history, **Namirial LTA Stored** confirms successful storage. See
[Archiving and retention](/products/namirialnotify/user-guides/archiving) for the full lifecycle.

## Next steps

- **Choose your API** — Read the use case table above and pick the service that matches your need. Then dive into its reference page.
- **Set up integration** — See [Development and integration guides](/products/namirialnotify/dev) for API collections, callback setup, and best practices.
- **Handle failures consistently** — Use the shared [Error handling](/products/namirialnotify/dev/error-handling) guide.
- **Follow end-to-end patterns** — Use [Integration workflows](/products/namirialnotify/dev/integration-patterns) for submit, track, and evidence retrieval flows.
- **Harden your integration** — Review [Security and authentication](/products/namirialnotify/dev/security-best-practices).
- **Plan for scale** — Review [Performance and scaling](/products/namirialnotify/dev/performance-guidelines).
- **Understand lifecycle** — Every message has a state and an outcome. Learn the difference in [States and outcomes](/products/namirialnotify/user-guides/states-outcomes).
- **Get evidence** — Understand how to request and use affidavits in [Evidence and affidavits](/products/namirialnotify/user-guides/evidences-affidavits).
- **Real-time updates** — Set up webhooks and read about callback payload structure in [Callbacks and webhooks](/products/namirialnotify/dev/callbacks).


## Related

- [Development and integration guides](/products/namirialnotify/dev)
- [Error handling](/products/namirialnotify/dev/error-handling)
- [Integration workflows](/products/namirialnotify/dev/integration-patterns)