EviSMS

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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.

This page explains EviSMS behaviour and includes guidance for API integrators. To send from the Web app, follow How to create a new EviSMS. For request and response definitions, see the EviSMS API reference.

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 when the certified communication is an email with attachments, HTML content, or commitment workflows. Use EviNotice when you need controlled access to the content, recipient authentication before reading, or explicit acceptance/rejection workflows.

How EviSMS works

Lifecycle overview

Key state transitions

New → Ready → Dispatched — These three transitions happen in rapid succession within a single processing step. By the time the platform fires the first callback, the message is typically already at Dispatched. The Ready event occurs before Dispatched, but their callbacks are delivered and retried independently.

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.

Delivered → Read — The recipient opened the message. RCS only, and only when the operator and recipient device support read receipts. This state is not reachable via SMS.

Delivered / Read / TTL / terminal failure → Closed — Plain SMS normally closes after delivery. RCS closes once the required delivery and read signals are available, or when the TTL elapses. A terminal failure also closes the lifecycle.

Submit a certified message

For API integrators. This section describes the Submit request. Web app users can follow the issuer guide.

POST /v1/EviSms/Submit

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

Required fields

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.

• 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 below.
• TimeToLive — minutes the platform will attempt delivery before the message expires. Range: 60–86,400 (1 hour to 60 days).
• 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.

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.

Recommended pattern for maximum reach with read evidence:

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

This attempts RCS first (with read receipt support) and falls back to SMS if RCS is unavailable. When the fallback fires, the state machine continues normally — Sent, Delivered, and Closed still apply regardless of which channel succeeded.

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

AdditionalData fields — always present

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 reliability

For your receiving application, follow Handling callbacks reliably. It explains how to process retries only once using Identifier, acknowledge a callback after safely storing it, and match it to your own records using AdditionalData.ExtraData.

Securing your callback endpoint

Use the shared callback endpoint controls to validate incoming requests. Correlation values do not authenticate the sender.

States reference

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

Querying status

For API integrators. This section explains programmatic status checks. In the Web app, use transaction search 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

If Limit is omitted, the API defaults to 100. The default drops to 25 when affidavit metadata is included.

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

Step 1 — Submit your first message

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

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

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

Confirm the message moves through New → Ready → Dispatched → Sent.

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. With the deprecated IncludeAffidavitBlobs=false, Query returns metadata rather than PDF bytes; callbacks never include the PDF.

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:

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 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:

• The message reaches Failed then Closed with Outcome: Failed
• A Failed callback fires to your endpoint

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

Related

• EviSMS API
• How to create a new EviSMS
• EviMail
• EviNotice
• API reference overview
• Callbacks and webhooks
• Security and authentication
• States and outcomes
• Evidence and affidavits