# EviMail API

REST API for submitting and querying certified emails through Namirial Notify, including on-demand affidavit generation for eligible transactions. EviMail provides legally binding certified email delivery with configurable certification levels, attachments, carbon copy recipients, and evidence collection options. For the public Namirial Notify API environments, this V1 service is exposed under the `/v1` base path. The `servers` entries below already include that public base path. Some lower-level technical artifacts may show the underlying route without the prefix. For customer integrations, use the public URLs produced by this specification.


Version: 1.0

## Servers

Production
```
https://api.evicertia.com/v1
```

Pre-production / QA
```
https://api.ecertia.com/v1
```

## Security

### basicAuth

Type: http
Scheme: basic

## Download OpenAPI description

[EviMail API](https://docs.namirial.app/_bundle/products/namirialnotify/apis/oas/evimail-api.yaml)

## EviMail

Certified email submission, query, and affidavit operations.

### Submit a certified email

 - [POST /EviMail/Submit](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail/evimailsubmit.md)

### Query certified emails (GET)

 - [GET /EviMail/Query](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail/evimailqueryget.md)

### Request an on-demand affidavit

 - [POST /EviMail/AffidavitRequest](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail/evimailaffidavitrequest.md): Generates a custom affidavit for a previously submitted EviMail. The original Submit request must have included AffidavitKinds containing OnDemand, and the communication must still be eligible for on-demand affidavits.

## EviMail Batch

Batch operations let you send the same certified email to many recipients as a single managed job.

**Workflow:**
1. **Create** an empty batch with a `Description` — you receive a `BatchId`.
2. **Set the body** (`PUT .../Body`) — the HTML email content.
3. **Add recipients** (`POST .../Recipients`) — uploaded as a `text/csv` file.
4. *(Optional)* **Add attachments** (`POST .../Attachments`) — uploaded as `multipart/form-data`.
5. **Configure options** (`PATCH .../{BatchId}`) — certification level, commitment, callbacks, scheduling, and so on. Also set the `Subject` here.
6. **Start processing** by setting the batch `State` (via `PATCH`) once the batch is ready.

Poll `GET .../{BatchId}` to follow progress (`SentCount`, `FailedCount`, `ProgressPercentage`). Batch lifecycle states: `Draft`, `Submitted`, `Scheduled`, `Processing`, `Processed`, `Invalid`, `Failed`.

:::note Base path and HTTP QUERY method
Unlike the rest of the EviMail v1 API, the batch endpoints are part of the **v2** API and live under the `/v2/EviMail/Batches` base path (not `/v1`).

The two list endpoints (`Batches` and `Batches/{BatchId}/Recipients`) use the HTTP `QUERY` method with their filters in a JSON request body. Because OpenAPI cannot express `QUERY`, they are documented as `GET` with the filter fields shown as query parameters — send the request with the HTTP `QUERY` verb and the fields in a JSON body.
:::


### Create an email batch

 - [POST /v2/EviMail/Batches](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchcreate.md): Creates a new, empty email batch. Only a Description is required at creation; the body, recipients, attachments, and options are set with the subsequent batch endpoints. Returns the BatchId used by all other batch operations.

### Query email batches (HTTP QUERY method)

 - [GET /v2/EviMail/Batches](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchesquery.md): Lists email batches owned by the caller (or the caller's site), with cursor pagination.

This endpoint uses the HTTP QUERY method, not GET. OpenAPI cannot express the QUERY method, so it is shown here as a GET with the filter fields as query parameters. In practice, send an HTTP QUERY request with the fields in a JSON body (States, Cursor, Limit, SortBy, SortOrder, Direction, TextSearch).

### Get an email batch

 - [GET /v2/EviMail/Batches/{BatchId}](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchget.md): Retrieves the full state of a batch, including its configured email template and processing progress.

### Update an email batch

 - [PATCH /v2/EviMail/Batches/{BatchId}](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchpatch.md): Updates batch metadata and the email template options. All fields are optional; only the fields supplied are changed. Setting State transitions the batch (for example, to start processing). Setting ScheduledDate schedules the batch.

### Delete an email batch

 - [DELETE /v2/EviMail/Batches/{BatchId}](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchdelete.md): Removes a previously created batch.

### Set the batch body

 - [PUT /v2/EviMail/Batches/{BatchId}/Body](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchbodyput.md): Sets the HTML body of the email for this batch. The body is sent as the raw request payload (HTML), not as a JSON field. Use PATCH .../{BatchId} to set the Subject.

### Add batch recipients (CSV)

 - [POST /v2/EviMail/Batches/{BatchId}/Recipients](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchrecipientspost.md): Adds recipients to the batch by uploading a text/csv file. The CSV uses ; as the column separator. Mandatory columns: emailaddress, legalname. Optional columns: lookupkey, displayname, evidenceaccesscontrolchallenge, evidenceaccesscontrolchallengeresponse. Custom per-recipient fields are added as extra columns prefixed with  (for example, orderid).

### Query batch recipients (HTTP QUERY method)

 - [GET /v2/EviMail/Batches/{BatchId}/Recipients](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchrecipientsquery.md): Lists the recipients of a batch, with cursor pagination.

This endpoint uses the HTTP QUERY method, not GET. OpenAPI cannot express the QUERY method, so it is shown here as a GET with the filter fields as query parameters. In practice, send an HTTP QUERY request with the fields (Cursor, Limit, SortDirection) in a JSON body.

### Delete all batch recipients

 - [DELETE /v2/EviMail/Batches/{BatchId}/Recipients](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchrecipientsdelete.md): Removes all recipients from the batch.

### Add a batch attachment

 - [POST /v2/EviMail/Batches/{BatchId}/Attachments](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchattachmentspost.md): Adds a single attachment to the batch by uploading it as multipart/form-data. The attachment is included in every email generated from the batch.

### List batch attachments

 - [GET /v2/EviMail/Batches/{BatchId}/Attachments](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchattachmentsget.md): Returns metadata for all attachments configured on the batch.

### Delete all batch attachments

 - [DELETE /v2/EviMail/Batches/{BatchId}/Attachments](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchattachmentsdelete.md): Removes all attachments from the batch.

### Download a batch attachment

 - [GET /v2/EviMail/Batches/{BatchId}/Attachments/{AttachmentId}](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchattachmentget.md): Downloads the binary content of a single batch attachment.

### Delete a batch attachment

 - [DELETE /v2/EviMail/Batches/{BatchId}/Attachments/{AttachmentId}](https://docs.namirial.app/products/namirialnotify/apis/oas/evimail-api/evimail-batch/evimailbatchattachmentdelete.md): Removes a single attachment from the batch.