API reference

Generated from the OpenAPI v1.0.0 contract, the API's source of truth.

Base URL: https://api.notify.com.mx/v1

Authentication

Send your API key as a Bearer token in the Authorization header. Your account is identified by the key.

Authorization: Bearer $NOTIFY_API_KEY

Send and query messages

GET`/messages`

List messages

Parameters

Name	In	Type	Required	Description
`status`	query	`MessageStatus`	No
`channel`	query	`Channel`	No
`recipient`	query	`string`	No	Recipient address
`from`	query	`string (date-time)`	No
`to`	query	`string (date-time)`	No
`cursor`	query	`string`	No	Cursor-based pagination
`limit`	query	`integer`	No

Responses

Code	Description	Type
`200`	Paginated list	`MessageList`
`401`	API key missing, invalid or revoked	`Error`

POST`/messages`

Send a message

Accepts a send request, validates it and queues it.

If the idempotency_key was already used, the original message is returned and no new send is created.
If the recipient has opted out of that channel, the message ends up in the blocked status.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	`string`	No	Prevents duplicate sends when the client retries.

Request body

SubmitMessageRequest

Responses

Code	Description	Type
`202`	Request accepted and queued	`Message`
`400`	Malformed request	`Error`
`401`	API key missing, invalid or revoked	`Error`
`403`	Tenant suspended	`Error`
`422`	Validation failed (template not found, required variable missing)	`Error`
`429`	Tenant rate limit exceeded	`Error`

GET`/messages/{id}`

Get a message's status

Returns the message status and its full history of delivery attempts.

A message that belongs to another tenant returns 404, never 403: a 403 would confirm that the identifier exists.

Parameters

Name	In	Type	Required	Description
`id`	path	`string (uuid)`	Yes

Responses

Code	Description	Type
`200`	Message found	`MessageDetail`
`401`	API key missing, invalid or revoked	`Error`
`404`	Resource not found or owned by another tenant	`Error`

GET`/health`

Health checkNo authentication

Responses

Code	Description	Type
`200`	Service is up	—

Multilingual templates

GET`/templates`

List templates

Parameters

Name	In	Type	Required	Description
`channel`	query	`Channel`	No

Responses

Code	Description	Type
`200`	Template list	`Template[]`

POST`/templates`

Create a template

Request body

CreateTemplateRequest

Responses

Code	Description	Type
`201`	Template created	`Template`
`409`	A template with that `key` already exists in the tenant	—
`422`	Validation failed (template not found, required variable missing)	`Error`

POST`/templates/{key}/versions`

Add a language version

Adds the template variant for a locale.

Editing an active version creates a new version; the previous one is never modified, so the audit trail can always recover the exact text that was sent in the past.

Parameters

Name	In	Type	Required	Description
`key`	path	`string`	Yes

Request body

CreateTemplateVersionRequest

Responses

Code	Description	Type
`201`	Version created	`TemplateVersion`
`404`	Resource not found or owned by another tenant	`Error`
`422`	Validation failed (template not found, required variable missing)	`Error`

Schemas

`Channel`

Delivery channel. push will be added in v2.

Values: email, sms, whatsapp

`MessageStatus`

accepted: accepted and queued
processing: a worker is processing it
sent: the provider accepted it
delivered: delivery to the recipient was confirmed
failed: retries were exhausted
blocked: not sent because of a registered opt-out

sent and delivered are deliberately different: a provider accepting a message does not prove it arrived.

Values: accepted, processing, sent, delivered, failed, blocked

`ErrorCategory`

Normalized taxonomy. The provider's raw error code is never exposed.

Values: transient_provider_error, rate_limited, invalid_recipient, blocked_by_provider, template_not_approved, authentication_error

`Recipient`

Name	Type	Required	Description
`address`	`string`	Yes	Email address, or phone number that will be normalized to E.164.
`locale`	`string`	No	Recipient language. If omitted, or if no version exists for it, the cascade applies: locale → tenant default_locale → es.
`external_id`	`string`	No	Recipient identifier in the customer's system.

`SubmitMessageRequest`

Name	Type	Required	Description
`channel`	`Channel`	Yes
`recipient`	`Recipient`	Yes
`template_key`	`string`	Yes	Stable template key.
`variables`	`object`	No	Render variables. Validated against the template's `variables_schema`.
`idempotency_key`	`string`	No	Alternative to the `Idempotency-Key` header.

`Message`

Name	Type	Required	Description
`id`	`string (uuid)`	No
`status`	`MessageStatus`	No
`channel`	`Channel`	No
`recipient`	`Recipient`	No
`template_key`	`string`	No
`resolved_locale`	`string`	No	Language actually used after applying the cascade.
`created_at`	`string (date-time)`	No

`DeliveryAttempt`

Name	Type	Required	Description
`attempt_number`	`integer`	No
`provider`	`string`	No
`status`	`sent` \| `failed`	No
`error_category`	`ErrorCategory`	No
`error_detail`	`string`	No	Human-readable explanation. Never the provider's raw message.
`attempted_at`	`string (date-time)`	No

`MessageDetail`

Name	Type	Required	Description
`id`	`string (uuid)`	No
`status`	`MessageStatus`	No
`channel`	`Channel`	No
`recipient`	`Recipient`	No
`template_key`	`string`	No
`resolved_locale`	`string`	No	Language actually used after applying the cascade.
`created_at`	`string (date-time)`	No
`attempts`	`DeliveryAttempt[]`	No
`delivered_at`	`string (date-time) \| null`	No

`MessageList`

Name	Type	Required	Description
`data`	`Message[]`	No
`next_cursor`	`string \| null`	No

`CreateTemplateRequest`

Name	Type	Required	Description
`key`	`string`	Yes	Unique per tenant. This is what the client references when sending.
`channel`	`Channel`	Yes
`name`	`string`	Yes
`variables_schema`	`object`	No	JSON Schema of the variables the template expects.

`Template`

Name	Type	Required
`id`	`string (uuid)`	No
`key`	`string`	No
`channel`	`Channel`	No
`name`	`string`	No
`variables_schema`	`object`	No
`versions`	`TemplateVersion[]`	No

`CreateTemplateVersionRequest`

Name	Type	Required	Description
`locale`	`string`	Yes
`subject`	`string`	No	Email channel only.
`body`	`string`	Yes	Content with variable placeholders.
`provider_template_id`	`string`	No	Required for WhatsApp: the ID of the Meta-approved template. WhatsApp does not allow free-form text outside the session window.

`TemplateVersion`

Name	Type	Required
`id`	`string (uuid)`	No
`locale`	`string`	No
`subject`	`string \| null`	No
`body`	`string`	No
`status`	`draft` \| `active` \| `archived`	No
`version`	`integer`	No

`Error`

Name	Type	Required	Description
`code`	`string`	Yes	Stable, actionable code.
`message`	`string`	Yes	Human-readable explanation of what to do.
`details`	`object`	No

API reference

Authentication

Send and query messages

GET/messages

Parameters

Responses

POST/messages

Parameters

Request body

Responses

GET/messages/{id}

Parameters

Responses

GET/health

Responses

Multilingual templates

GET/templates

Parameters

Responses

POST/templates

Request body

Responses

POST/templates/{key}/versions

Parameters

Request body

Responses

Schemas

Channel

MessageStatus

ErrorCategory

Recipient

SubmitMessageRequest

Message

DeliveryAttempt

MessageDetail

MessageList

CreateTemplateRequest

Template

CreateTemplateVersionRequest

TemplateVersion

Error

GET`/messages`

POST`/messages`

GET`/messages/{id}`

GET`/health`

GET`/templates`

POST`/templates`

POST`/templates/{key}/versions`

`Channel`

`MessageStatus`

`ErrorCategory`

`Recipient`

`SubmitMessageRequest`

`Message`

`DeliveryAttempt`

`MessageDetail`

`MessageList`

`CreateTemplateRequest`

`Template`

`CreateTemplateVersionRequest`

`TemplateVersion`

`Error`