Submit one message through a sender profile the caller's access profile lists, rendered from a template version at acceptance or, where the profile allows it, from direct content. The `Idempotency-Key` header is required: the same key and request answer the stored receipt again.
const url = 'https://example.com/v1/messages';const options = { method: 'POST', headers: { 'idempotency-key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"content":{"subject":"example","text":"example"},"correlationId":"example","data":"example","expiresAt":"2026-04-15T12:00:00Z","locale":"example","notBefore":"2026-04-15T12:00:00Z","senderProfile":"example","template":{"id":"example","version":"example"},"to":{"email":"example"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/messages \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'idempotency-key: example' \ --data '{ "content": { "subject": "example", "text": "example" }, "correlationId": "example", "data": "example", "expiresAt": "2026-04-15T12:00:00Z", "locale": "example", "notBefore": "2026-04-15T12:00:00Z", "senderProfile": "example", "template": { "id": "example", "version": "example" }, "to": { "email": "example" } }'Authorizations
Section titled “Authorizations”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters”Scopes a retry to the caller: the same key and request answer the stored receipt again.
Request Bodyrequired
Section titled “Request Bodyrequired”One message: a template version with its locale and data, or direct content where the access profile allows it, never both. Every endpoint, credential, and script is bound by the operator; no member chooses one.
object
Direct content, instead of template.
object
An opaque caller reference, stored, returned, and audited, never interpreted. The runtime bounds it at 128 UTF-8 bytes, not characters, and refuses control characters.
The template data, validated against the template version’s schema; required with template. It is rendered at acceptance and never stored.
The instant an unsent message expires. It must lie within retention.payloadDays of acceptance, and defaults to the sender profile’s expiry.
A locale the template version declares; required with template.
The earliest instant the message may be sent.
A sender profile the caller’s access profile lists.
object
Examplegenerated
{ "content": { "subject": "example", "text": "example" }, "correlationId": "example", "data": "example", "expiresAt": "2026-04-15T12:00:00Z", "locale": "example", "notBefore": "2026-04-15T12:00:00Z", "senderProfile": "example", "template": { "id": "example", "version": "example" }, "to": { "email": "example" }}Responses
Section titled “ Responses ”The operation succeeded.
object
object
Derived from dispatch and report: the dispatch state, except that a submitted message whose report is delivered is delivered, and one whose report is undelivered is failed.
Example
{ "status": "queued"}A problem: request.invalid.
object
Example
{ "code": "request.invalid", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: authentication.refused.
object
Example
{ "code": "authentication.refused", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}Headers
Section titled “Headers”The bearer challenge.
A problem: operation.not-authorized, profile.not-authorized.
object
Example
{ "code": "operation.not-authorized", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: template.not-found.
object
Example
{ "code": "template.not-found", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: request.method-not-allowed.
object
Example
{ "code": "request.method-not-allowed", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: idempotency.key-reused.
object
Example
{ "code": "idempotency.key-reused", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: idempotency.expired.
object
Example
{ "code": "idempotency.expired", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: request.body-too-large.
object
Example
{ "code": "request.body-too-large", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: request.unsupported-media-type.
object
Example
{ "code": "request.unsupported-media-type", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: request.unprocessable, content.invalid, content.too-large, content.too-many-segments, template.data-invalid, template.locale-unavailable, template.render-refused.
object
Example
{ "code": "request.unprocessable", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}A problem: rate-limit.exceeded, quota.exceeded.
object
Example
{ "code": "rate-limit.exceeded", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}Headers
Section titled “Headers”Whole seconds to wait before trying again.
A problem: service.unavailable.
object
Example
{ "code": "service.unavailable", "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"}Headers
Section titled “Headers”Whole seconds to wait before trying again.