MessageMedia connector — endpoints

How to call the connector. The formal schema is the OpenAPI specification (Notification, openapi/source/connector/notifications/notifications.yml — shared across Ark's SMS connectors); this page covers the call contract and examples. Internal processing is in the architecture; caveats in the connector notes.

This is an internal connector API called by the Ark Platform. Message content arrives already templated/validated by the Platform.

Authentication

All /v1/notifications/* endpoints require a bearer token (OAuth2 client-credentials JWT). Health endpoints are unauthenticated probes.

Method	Path	Purpose
POST	/v1/notifications	Send or schedule an SMS
GET	/v1/notifications	List notifications (optional id filter)
GET	/v1/notifications/{notificationId}	Get one notification
DELETE	/v1/notifications/{notificationId}	Cancel a scheduled SMS
POST	/v1/notifications/{notificationId}/purge	Purge a notification
GET	/health · /health/readiness · /health/liveness	Probes (see architecture)

All responses wrap a NotificationData object: { notificationId, status, vendorId?, deliveryDateTime?, isPurged, errorDetails? }. status is the normalised Ark status (lifecycle); vendorId is the MessageMedia message id.

---

POST /v1/notifications — send or schedule

Body — SendNotificationRequest:

Field	Required	Notes
notificationId	✓	UUID; the Ark id used for lookup, cancel, purge
contactChannel	✓	Must be SMS — anything else → 400 (see the connector notes)
channelIdentifier	✓	Recipient phone in E.164 format
messageContent	✓ (for SMS here)	Final message text; must be non-empty
messageType	✓ in schema	Accepted but not used by the connector
scheduledDateTime	—	ISO-8601; if present, must be > 5 min and ≤ 35 days ahead
templateId / templateVariables	—	Accepted by the schema but not used — templating is the Platform's job

// Request
{ "notificationId": "12345678-1234-1234-1234-123456789abc",
  "contactChannel": "SMS", "channelIdentifier": "+61491570006",
  "messageContent": "Your account balance is $1,234.56" }
// Response (SendNotificationResponse) — status reflects the MessageMedia send response
{ "notification": { "notificationId": "1234…abc", "vendorId": "…", "status": "NEW",
                    "deliveryDateTime": null, "isPurged": false } }

---

GET /v1/notifications — list

Param	In	Required	Notes
arkNotificationIds	query	—	Comma-separated Ark ids to filter by; omit for all

Returns { "notifications": NotificationData[] }, read from the local store (not MessageMedia).

GET /v1/notifications/{notificationId} — get one

Returns one NotificationData (with errorDetails if a send failed). 404 if unknown.

DELETE /v1/notifications/{notificationId} — cancel

Cancels a scheduled SMS at MessageMedia and marks it CANCELLED. Only notifications whose stored status is scheduled, queued, or processing can be cancelled.

• 404 if unknown / never reached MessageMedia (or MessageMedia returns 404); 412 if not in a cancellable state.

POST /v1/notifications/{notificationId}/purge — purge

Flags the local record purged (isPurged: true) for compliance. This is a local-only purge — the connector does not call MessageMedia to delete the message (see the connector notes). Idempotent: an already-purged or never-sent record returns its current state.

• 404 if unknown.

---

Errors

HTTP	Code	When
400	GEN000000	Request body/params fail schema validation
400	NOT000001	contactChannel is not SMS
400	NOT000004	Missing message content
401	GEN001002	Missing or invalid bearer token
404	NOT004001	No notification for the id (or MessageMedia 404 on cancel)
412	NOT012001	Cancel attempted on a non-cancellable status
422	NOT022003	scheduledDateTime outside the 5-min–35-day window
500	NOT100002	Local database write failure
500	NOT100004	MessageMedia send/credential failure, or an empty/idless response
500	NOT100006	MessageMedia cancellation failure