# EviSMS

EviSMS is the Namirial Notify service for sending certified mobile communications through SMS and RCS. In the standard EviSMS flow, the certified content is the message itself — delivered directly to the recipient's device, with evidence recorded for processing, sending, delivery, and where supported, reading.

**EviSMS is a direct-message service**

The certified content is the message itself, delivered straight to the recipient's device. If you need hosted content, recipient authentication before reading, or formal accept/reject interactions, use [EviNotice](/products/namirialnotify/services/evinotice) instead.

This page explains EviSMS behaviour and includes guidance for API integrators. To send from the Web app, follow [How to create a new EviSMS](/products/namirialnotify/issuer/create-evisms). For request and response definitions, see the [EviSMS API reference](/products/namirialnotify/apis/evisms-api).

## When to use EviSMS

Use EviSMS when:

- **You need certified delivery directly to a mobile device** — in the standard flow, the message arrives in the recipient's SMS inbox or RCS client without requiring them to follow a link or open a hosted page.
- **Speed and reach are priorities** — SMS reaches virtually any mobile number worldwide; RCS adds richer formatting and read receipts where the operator supports it.
- **The communication fits within mobile message constraints** — the certified content is the SMS or RCS message text itself.


Use [EviMail](/products/namirialnotify/services/evimail) when the certified communication is an email with attachments, HTML content, or commitment workflows. Use [EviNotice](/products/namirialnotify/services/evinotice) when you need controlled access to the content, recipient authentication before reading, or explicit acceptance/rejection workflows.

## How EviSMS works

### Lifecycle overview

```mermaid
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#E4F2F2', 'primaryBorderColor': '#006660', 'primaryTextColor': '#0A1111', 'lineColor': '#047C76', 'secondaryColor': '#CDDBDB', 'tertiaryColor': '#f5fafa', 'edgeLabelBackground': '#f5fafa', 'transitionColor': '#047C76'}}}%%
stateDiagram-v2
    [*] --> New : Submit accepted
    New --> Ready : Validated and certified
    Ready --> Dispatched : Queued for channel dispatch
    Dispatched --> Sent : Operator accepted message for routing
    Sent --> Delivered : Delivery confirmation received
    Sent --> Read : RCS read receipt can arrive first
    Delivered --> Read : RCS read receipt
    Delivered --> Closed : SMS delivered or RCS tracking ends
    Read --> Closed : RCS delivery receipt or tracking ends
    Sent --> Closed : TimeToLive elapsed
    Dispatched --> Failed : Transmission failure recorded
    Sent --> Failed : Delivery failure recorded
    Dispatched --> Closed : Tracking ends without a send result
    Failed --> Closed : Tracking ends after failure
```

This diagram shows common paths. A failed attempt may be retried or trigger fallback without setting `State: Failed`. If `Failed` is recorded, a later successful signal can still advance the state before closure. Wait for `Closed` and inspect `Outcome`.

### Key state transitions

**New → Ready → Dispatched** — The platform admits the message as `New`. The background worker records `Ready` and requests dispatch in the same processing step. On a new submission, `ReadyOn` is populated when Ready is recorded and carries the original admission time from `NewOn`. It does not measure processing duration. The `Ready` and `Dispatched` callbacks can arrive out of order.

**Dispatched → Sent** — The SMS or RCS operator accepted the message for routing.

**Sent → Delivered** — A delivery confirmation was received from the operator. For SMS this is a delivery receipt; for RCS this is a delivery acknowledgement.

**Read (RCS only)** — The platform recorded a read receipt. Delivery and read receipts can arrive independently, and an SMS delivery never produces a read receipt.

**Closed** — SMS normally closes after confirmed delivery. RCS can close after recording both delivery and read receipts for the same send, in either order, or when the tracking window expires. A message can also close without a delivery receipt or without entering `Failed`. Check the final `Outcome`.

## Submit a certified message

**For API integrators.** This section describes the Submit request. Web app users can follow the [issuer guide](/products/namirialnotify/issuer/create-evisms).

```
POST /v1/EviSms/Submit
```

Returns `{ "eviId": "..." }` on success.

### Required fields

| Field | Description |
|  --- | --- |
| `Text` | The content of the SMS or RCS message. This is the certified content delivered to the recipient. |
| `Recipient.PhoneNumber` | The recipient's mobile number in E.164 format (e.g. `+34600000000`). |


### Useful fields you should configure

- **`LookupKey`** — your own correlation key, filterable in Query. No uniqueness enforced server-side.
- **`IssuerName`** — the legal name or short identifier of the sending organisation, recorded in the certification evidence. This is **not** the sender shown in the recipient's inbox — the inbox sender (the alphanumeric sender ID or number) is configured at the account level, separately from `IssuerName`.
- **`Recipient.LegalName`** — the legal name of the recipient, recorded in the certification evidence.


### Options

All delivery and certification configuration lives inside the `Options` object.

Every field in `Options` is optional at the API level. When you omit one, the platform applies a default — for example single-message Submit uses SMS when no delivery channels are provided and uses English for `Language` and `AffidavitLanguage` unless the site's legacy language setting applies. The web form has its own site and user defaults. Submit requires the fields listed under [Required fields](#required-fields) above. Some settings have additional requirements: `Challenge` needs a challenge and response, and the `Read` affidavit requires RCS.

- **`CertificationLevel`** — the legal framework applied. Supported values include `Standard`, `Advanced`, and regional variants such as `Standard_EU` or `Advanced_EU`. Available levels depend on your account subscription.
- **`DeliveryChannels`** — the channel or channels to use. Supported values: `SMS`, `RCS`. When both are specified, Namirial Notify attempts delivery in priority order. See [Delivery channels](#delivery-channels) below.
- **`TimeToLive`** — minutes the platform will attempt delivery before the message expires. The single-message API accepts 1–86,400 minutes. Portal settings can have a higher minimum.
- **`Language`** — language for any platform-generated notification text. Accepted values: `ca`, `de`, `en`, `es`, `fr`, `it`, `pt`, `pt-BR`, `ro`.
- **`AffidavitLanguage`** — language for generated affidavit PDFs. Accepts `el` (Greek) in addition to `Language` values.
- **`DeliveryAppearance`** — controls whether the delivered message uses the certified presentation or the plain `AsIs` appearance.
- **`EvidenceAccessControlMethod`** — controls how the recipient accesses the evidence record. Supported values: `Public`, `Challenge`, `AutoChallenge`. When omitted, the account's configured default method applies.
- **`OnlineRetentionPeriod`** — number of years the message and its evidence remain accessible online.


**EviSMS does not support commitment**

EviSMS has no accept/reject (commitment) functionality. If you need acceptance or rejection workflows, use [EviNotice](/products/namirialnotify/services/evinotice) instead — it exposes this through a field named `CommitmentChoice`.

### Callbacks

- **`PushNotificationUrl`** — HTTPS endpoint to receive state callbacks. Must be publicly reachable.
- **`PushNotificationFilter`** — state transitions that trigger a callback. Valid values: `Ready`, `Sent`, `Dispatched`, `Delivered`, `Read`, `Failed`, `Closed`, `AffidavitPublished`. `AffidavitPublished` is a platform meta-event that fires when affidavit generation completes — it is not a lifecycle state.
- **`PushNotificationExtraData`** — arbitrary string echoed back in every callback. Use it to embed a routing key or internal record ID.


### 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 message is not resubmitted.

## Delivery channels

`DeliveryChannels` accepts `SMS`, `RCS`, or both. When both are specified, the platform attempts delivery in the order listed. SMS content is limited by the configured segment count. RCS text is limited to 3,072 UTF-16 code units. With both channels selected, the text must meet both limits.

| Channel | Delivery evidence | Read evidence | Fallback |
|  --- | --- | --- | --- |
| `SMS` | Operator delivery receipt | Not supported | — |
| `RCS` | Operator delivery acknowledgement | Supported where operator and device allow | Falls back to SMS when specified as second channel |


**Recommended pattern for maximum reach with read evidence:**

```json
"DeliveryChannels": ["RCS", "SMS"]
```

This attempts RCS first. A qualifying failure can trigger an SMS attempt if there is sufficient time for fallback. A missing RCS read receipt alone does not trigger fallback.

## 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`.

### Base payload

| Field | Type | Description |
|  --- | --- | --- |
| `Identifier` | string | Event ID for lifecycle callbacks and affidavit ID for `AffidavitPublished`. Retries retain the same identifier. |
| `Kind` | string | The state or event that triggered this callback (e.g. `Sent`, `Delivered`, `Read`, `Closed`, `AffidavitPublished`). |
| `Date` | datetime | UTC timestamp associated with `Kind`. `Ready` carries the admission time (`NewOn`). A fallback `Dispatched` callback has a new `Identifier` and repeats the first `DispatchedOn`. `AffidavitPublished` carries the publication time. |
| `EvidenceId` | UUID | The `eviId` of the EviSMS, as returned at submission. |
| `EvidenceType` | string | Always `eviSMS` for EviSMS callbacks. |
| `EvidenceState` | string/null | Not populated by this service. Accept an absent or null value and use `AdditionalData.State`. |
| `Site` | string | Name of the issuer's site. |
| `Owner` | string/null | Not populated by this service. Accept an absent or null value; do not require it. |
| `OwnerEmail` | string | Email address of the submitting account. |
| `AdditionalData` | object | Common and event-specific fields described below. |


### `AdditionalData` fields — always present

| Field | Description |
|  --- | --- |
| `Source` | The sender display name (the account-configured sender), not the submitted `IssuerName`. |
| `Destination` | Recipient phone number. |
| `LookupKey` | The integrator-assigned lookup key set at submission. |
| `State` | Current lifecycle state. |
| `CreationDate` | Timestamp when the message was submitted. |


### 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 `Kind` | Extra fields |
|  --- | --- |
| `Sent` | `XmissionDetails` — technical details of the transmission. |
| `Dispatched`, `Delivered`, `Read`, `Failed` | `Progress` and `Description` — labels for the event. For failures, use Query and the transaction history to investigate the cause. |
| `Closed` | `Outcome` — the final outcome of the message lifecycle. `OutcomeDescription` — human-readable description of the outcome. |
| `AffidavitPublished` | `AffidavitId` — unique ID of the generated affidavit. `AffidavitKind` — the kind generated. `AffidavitName` — filename of the affidavit PDF. `Regenerated: true` is present when the affidavit was regenerated. |


### Callback reliability

For your receiving application, follow [Handling callbacks reliably](/products/namirialnotify/dev/callbacks#handling-callbacks-reliably). Deduplicate using `EvidenceType`, `EvidenceId`, `Kind`, and `Identifier`. An HTTP retry reuses the original payload. The platform can emit the same event again with updated `AdditionalData`, so use the deduplication key even when the payload differs. Acknowledge the callback after safely storing it and use `AdditionalData.ExtraData` to match it to your records.

### Securing your callback endpoint

Use the shared [callback endpoint controls](/products/namirialnotify/dev/security-best-practices#callback-endpoint-hardening) to validate incoming requests. Correlation values do not authenticate the sender.

## States reference

| State | Description |
|  --- | --- |
| `Unknown` | State is not known or has not been mapped. |
| `Draft` | Message has been staged but not yet submitted. |
| `New` | Message has been accepted by the platform. |
| `Ready` | Message has been validated, certified, and queued for dispatch. Transitions to `Dispatched` immediately. |
| `Dispatched` | Message has been handed to the sending process and is ready for the operator. |
| `Sent` | The SMS or RCS operator accepted the message for routing. |
| `Delivered` | Delivery confirmation received from the operator. |
| `Read` | Recipient opened the message. **RCS only**, where the operator and device support read receipts. |
| `Closed` | Message lifecycle is complete. |
| `Failed` | A processing, transmission, or delivery failure was recorded. A failed attempt can be retried or can trigger channel fallback without setting this state. Wait for `Closed` and check `Outcome` for the final result. |


**On `Ready`:** this state is extremely transient — the platform moves from `Ready` to `Dispatched` in the same processing step. The `Ready` event occurs before `Dispatched`, but their callbacks are delivered and retried independently, so do not rely on callback arrival order.

**On `Read`:** only reachable via RCS. When the delivery channel is SMS, `Read` will never fire. Plan your callback handling to treat `Read` as optional enrichment rather than a required step.

## 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.

### When each affidavit is generated

| `AffidavitKinds` value | Triggers at | Notes |
|  --- | --- | --- |
| `Submitted` | `Ready` | Certifies the message content at submission time. |
| `SubmittedAdvanced` | `Ready` | Advanced variant with extended content certification. |
| `TransmissionResult` | Transmission result | Records the result of sending, which can be unsuccessful. |
| `DeliveryResult` | Delivery result | Records successful or unsuccessful delivery feedback. Check the event and `DeliveredOn` before treating it as proof of delivery. |
| `Read` | `Read` | Records an RCS read receipt. |
| `Closed` | `Closed` | Certifies the end of the message lifecycle. |
| `ClosedAdvanced` | `Closed` | Advanced variant of the closure affidavit. |
| `Complete` | `Closed` | Certifies the full chain from submission to closure. |
| `CompleteAdvanced` | `Closed` | Advanced variant of the complete lifecycle affidavit. |
| `Event` | Various technical events | Internal technical record for events without a more specific affidavit kind. |


## Querying status

**For API integrators.** This section explains programmatic status checks. In the Web app, use [transaction search](/products/namirialnotify/issuer/transactions-search-evisms) 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.

```
GET /v1/EviSms/Query
```

The default and maximum `Limit` are 100 for message results, 25 when including affidavit metadata without blobs, and 1 when including affidavit blobs. ASP.NET defaults `IncludeAffidavitBlobs` to `false`; legacy uses a deployment setting whose declared default is `true`. For metadata only, always send `IncludeAffidavits=true&IncludeAffidavitBlobs=false`.

Common filters:

- `WithLookupKeys=your-key` — fetch by your correlation key.
- `OnState=Closed` — fetch only closed messages.
- `WithOutcome=Delivered` — fetch by final outcome.


## 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 mobile number for testing
- A dedicated non-production HTTPS endpoint that you control for callbacks; use synthetic data and follow the [callback testing guidance](/products/namirialnotify/dev/security-best-practices#callback-endpoint-hardening)


### Step 1 — Submit your first message

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

```bash
curl -X POST "https://api.evicertia.com/v1/EviSms/Submit" \
  -u "$EVI_USER:$EVI_PASS" \
  -H "Content-Type: application/json" \
  -H "X-Evi-IdempotencyToken: $EVI_IDEMPOTENCY_TOKEN" \
  -d '{
    "Text": "This is a test certified SMS message.",
    "LookupKey": "test-001",
    "IssuerName": "TestCo",
    "Recipient": {
      "PhoneNumber": "+34600000000"
    },
    "Options": {
      "CertificationLevel": "Standard_EU",
      "DeliveryChannels": ["SMS"],
      "AffidavitKinds": ["Submitted", "DeliveryResult", "Closed"],
      "PushNotificationUrl": "https://your-endpoint.example.com/callbacks",
      "PushNotificationFilter": ["Sent", "Delivered", "Closed", "AffidavitPublished"]
    }
  }'
```

A `200 OK` response contains `{ "eviId": "..." }`. Store the `eviId`.

### Step 2 — Verify the message progresses

```bash
curl "https://api.evicertia.com/v1/EviSms/Query?WithLookupKeys=test-001" \
  -u "$EVI_USER:$EVI_PASS"
```

Check the recorded milestones in the Query response. A poll can miss short-lived states such as `Ready`.

### Step 3 — Confirm delivery

Confirm that a `Sent` callback fires and that `SentOn` is populated in the Query response. If the operator provides a delivery signal, also verify the `Delivered` callback and `DeliveredOn`. If you requested a delivery affidavit, verify that the `DeliveryResult` affidavit appears through an `AffidavitPublished` callback; the affidavit kind alone is not proof of successful delivery.

### Step 4 — Download an affidavit

Use `AdditionalData.AffidavitId` from an `AffidavitPublished` callback, or query
with `IncludeAffidavits=true` and copy the affidavit `uniqueId`. Set the deprecated `IncludeAffidavitBlobs` parameter to `false` to return
metadata without PDF bytes. Callbacks never include the PDF.

```bash
curl "https://api.evicertia.com/v1/EviSms/Query?WithLookupKeys=test-001&IncludeAffidavits=true&IncludeAffidavitBlobs=false" \
  -u "$EVI_USER:$EVI_PASS"
```

Pass the affidavit ID to the shared download endpoint. The response is a ZIP
archive containing the requested signed PDF:

```bash
curl -X POST "https://api.evicertia.com/AffidavitsDownload" \
  -u "$EVI_USER:$EVI_PASS" \
  -H "Content-Type: application/json" \
  --data '{"UniqueIds":["000c1f70-42ac-a3ea-149f-943879726a87"]}' \
  --output affidavits.zip
```

Replace the sample UUID with the affidavit ID from your callback or Query
response. See [Shared download APIs](/products/namirialnotify/apis/downloads-api#download-affidavit-pdfs-by-id)
for the complete response and error contract.

### Step 5 — Test the failure path

Submit a message to a well-formed number that is known to return a permanent delivery failure. Confirm the test number with your Namirial Notify contact so the result is deterministic. Verify that:

- Query reaches `Closed` and reports the final `Outcome`.
- If the platform records `Failed`, the `Failed` callback can arrive separately from `Closed`. Subscribe to both events for this test.


## Integration checklist

- Set `LookupKey` on every Submit and persist `eviId` from the response.
- Send `X-Evi-IdempotencyToken` (UUIDv4) on every Submit. Treat `202 Accepted` as success.
- Set `IssuerName` to the issuer's legal name or identifier for the evidence record. It does not control the sender shown in the recipient's inbox.
- When using `["RCS", "SMS"]` as `DeliveryChannels`, handle callbacks for both channels — the `Sent` and `Delivered` callbacks fire regardless of which channel succeeded.
- Do not rely on `Ready` callbacks for business logic — the state is transient and `Dispatched` follows immediately.
- Subscribe to `Read` only if you specifically need read receipt evidence and are using RCS — it will never fire for SMS-only deliveries.
- Include `AffidavitPublished` in `PushNotificationFilter` if you download affidavits programmatically.
- Make your callback handler idempotent, keyed on `EvidenceType`, `EvidenceId`, `Kind`, and `Identifier`.
- Use Query as a fallback when callbacks lag.


## Troubleshooting

The table below covers API integration issues. For Web app issues, see the [EviSMS issuer guide](/products/namirialnotify/issuer/create-evisms#troubleshooting).

| Symptom | Likely causes | What to check | What to do |
|  --- | --- | --- | --- |
| No callbacks received | `PushNotificationUrl` missing or unreachable; `PushNotificationFilter` omits the `Kind` you expect; endpoint returned non-2xx and retries exhausted | Query state directly; server access logs for the callback `Identifier` | Confirm URL and filter; use Query polling as fallback |
| Message stays in `Dispatched` or `Sent` | Operator processing delay; recipient device off or unreachable | `SentOn`, `DeliveredOn` timestamps in Query | Wait; do not resubmit |
| Recipient did not receive the SMS | Wrong number; operator routing issue; spam filter on device | `Delivered` callback and `DeliveredOn` timestamp | Confirm the number is valid E.164; retry with a new idempotency token |
| `Read` callback never fires | Delivery channel is SMS (not RCS); recipient device does not support RCS read receipts; operator does not pass read events | `DeliveryChannels` in your submit request | Expected behaviour for SMS — treat `Read` as optional enrichment |
| Message closed with `Outcome: Failed` | A processing, transmission, or delivery failure was recorded before closure | `FailedOn`, callback payloads, and failure details | Correct the number or configuration; resubmit with a new idempotency token only after the cause is fixed |
| Affidavit not available | Generation is asynchronous; `AffidavitPublished` has not fired yet; the kind was not included in `AffidavitKinds` at submission | Query with `IncludeAffidavits=true&IncludeAffidavitBlobs=false` | Wait for `AffidavitPublished`; if kind is missing it cannot be added retroactively — resubmit |
| Submit → `400 Bad Request` | Missing `Text` or `Recipient.PhoneNumber`; invalid `CertificationLevel`; other field-level validation failure | `responseStatus.errors[]` for field-level details | Fix the flagged field; retry with a new idempotency token |
| Submit → `401 Unauthorized` | Wrong environment base URL; credentials rotated | `Authorization` header; confirm target environment | Re-issue credentials |
| Submit → `403 Forbidden` | Account not provisioned for EviSMS | Account permissions | Contact your Namirial Notify account manager |


## Related

- [EviSMS API](/products/namirialnotify/apis/evisms-api)
- [How to create a new EviSMS](/products/namirialnotify/issuer/create-evisms)
- [EviMail](/products/namirialnotify/services/evimail)
- [EviNotice](/products/namirialnotify/services/evinotice)
- [API reference overview](/products/namirialnotify/apis/overview)
- [Callbacks and webhooks](/products/namirialnotify/dev/callbacks)
- [Security and authentication](/products/namirialnotify/dev/security-best-practices)
- [States and outcomes](/products/namirialnotify/user-guides/states-outcomes)
- [Evidence and affidavits](/products/namirialnotify/user-guides/evidences-affidavits)