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.

:::info 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 instead. :::

For the API reference, see the 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 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

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.

:::info EviSMS does not support commitment EviSMS has no accept/reject (commitment) functionality. If you need acceptance or rejection workflows, use 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.

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

When a state in PushNotificationFilter is reached, Namirial Notify sends an HTTP POST to PushNotificationUrl.

Base payload

AdditionalData fields — always present

AdditionalData fields — per event

Callback reliability

Make your handler idempotent, keyed on Identifier. Return 2xx promptly. Use PushNotificationExtraData to embed a routing key for correlation without a separate API call.

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

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

What you need

• Namirial Notify credentials (username and password)
• A recipient mobile number for testing
• An HTTPS endpoint to receive callbacks (or use a tool like Webhook.site for initial testing)

Step 1 — Submit your first message

POST /v1/EviSms/Submit
Authorization: Basic <base64(username:password)>
Content-Type: application/json
X-Evi-IdempotencyToken: <uuid>

{
  "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

GET /v1/EviSms/Query?WithLookupKeys=test-001
Authorization: Basic <base64(username:password)>

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

Related

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