Without scheduled_at, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in pending (or already dispatched when nobody is waiting), and GET it to follow the send. With scheduled_at (ISO 8601, inside the window the preview’s schedule reports), the alert is stored as scheduled and sent by the system at that time, after the same balance check. Send an Idempotency-Key: a retry after a timeout must not alert everyone twice.
An API key created by the chain owner in the panel (Integrações → Nova chave), sent as Authorization: Bearer <key>. The key (<id>|na_…) is shown once, at creation; rotate or revoke it on the same screen. It is a server secret: never ship it in browser or mobile code.
Makes the request safe to retry. Send a value unique to this intended operation — a UUID v4 is recommended. The first response, a success or a business-rule refusal (any error with its own code, including dispatch_in_progress and dispatch_too_soon), is stored for 24 hours and replayed to a repetition with the same key and body, byte for byte and with its original Content-Language, under Idempotent-Replayed: true. A stored refusal is not retried: to try again for real, send a new key. validation_failed, forbidden and server errors are not stored. The same key with a different body is a 422 idempotency_key_reused; a repetition while the first request still runs is a 409 idempotency_request_in_progress. A replay counts towards the rate limit.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Need Alert","description":"Avise seus clientes no momento em que o que eles esperam fica disponível.","colors":{"primary":"#465FFF","light":"#7C8CFF","dark":"#3641CC"},"logo":{"light":"https://mintcdn.com/need-alert/9mmUrKHe_2MF526d/logo/light.svg?fit=max\u0026auto=format\u0026n=9mmUrKHe_2MF526d\u0026q=85\u0026s=373a6fb813b58847213edb4a69e07fc2","dark":"https://mintcdn.com/need-alert/9mmUrKHe_2MF526d/logo/dark.svg?fit=max\u0026auto=format\u0026n=9mmUrKHe_2MF526d\u0026q=85\u0026s=30c19faa6f0c69ad4ce03787eb0be7fd"},"favicon":"https://mintcdn.com/need-alert/9mmUrKHe_2MF526d/favicon.svg?fit=max\u0026auto=format\u0026n=9mmUrKHe_2MF526d\u0026q=85\u0026s=3232d54c500467b3b6694a4c942ed879","api":{"playground":{"display":"interactive"},"examples":{"defaults":"required","languages":["curl","javascript","python","php"]}},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":false},"navigation":{"languages":[{"language":"pt-BR","default":true,"href":""},{"language":"en","href":"en"}]}},"deployment":{"deploymentMetadataValue":{"subdomain":"need-alert","hasAudioNarration":false,"actualSubdomain":"need-alert","customDomains":["docs.needalert.app"],"gitSource":{"type":"github","owner":"claudiusnascimento","repo":"docs-need-alert","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6ad760e76e89f16d0373b3c1","clientVersion":"0.0.4111","searchFilterCounts":[{"language":"pt-BR","tag":"API","count":26},{"language":"en","tag":"API","count":26},{"language":"pt-BR","tag":"Guias","count":18},{"language":"pt-BR","tag":"Endpoints","count":18},{"language":"en","tag":"Guides","count":18},{"language":"en","tag":"Endpoints","count":18},{"language":"pt-BR","tag":"Para estabelecimentos","count":8},{"language":"pt-BR","tag":"Items","count":8},{"language":"en","tag":"For establishments","count":8},{"language":"en","tag":"Items","count":8},{"language":"pt-BR","tag":"Dispatches","count":6},{"language":"en","tag":"Dispatches","count":6},{"language":"pt-BR","tag":"Para quem espera","count":4},{"language":"en","tag":"For people waiting","count":4},{"language":"pt-BR","tag":"Introdução","count":3},{"language":"pt-BR","tag":"Começando","count":3},{"language":"en","tag":"Introduction","count":3},{"language":"en","tag":"Getting started","count":3},{"language":"pt-BR","tag":"Convenções","count":2},{"language":"en","tag":"Conventions","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api/reference/dispatches/send-or-schedule-an-alert","slug":"/api/reference/dispatches/send-or-schedule-an-alert","pageMetadata":{"title":"Send or schedule an alert","description":"Without `scheduled_at`, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in `pending` (or already `dispatched` when nobody is waiting), and `GET` it to follow the send. With `scheduled_at` (ISO 8601, inside the window the preview's `schedule` reports), the alert is stored as `scheduled` and sent by the system at that time, after the same balance check. Send an `Idempotency-Key`: a retry after a timeout must not alert everyone twice.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /establishments/{establishment}/items/{item}/events","href":"/api/reference/dispatches/send-or-schedule-an-alert","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Without \", _jsx(_components.code, {\n children: \"scheduled_at\"\n }), \", notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in \", _jsx(_components.code, {\n children: \"pending\"\n }), \" (or already \", _jsx(_components.code, {\n children: \"dispatched\"\n }), \" when nobody is waiting), and \", _jsx(_components.code, {\n children: \"GET\"\n }), \" it to follow the send. With \", _jsx(_components.code, {\n children: \"scheduled_at\"\n }), \" (ISO 8601, inside the window the preview’s \", _jsx(_components.code, {\n children: \"schedule\"\n }), \" reports), the alert is stored as \", _jsx(_components.code, {\n children: \"scheduled\"\n }), \" and sent by the system at that time, after the same balance check. Send an \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \": a retry after a timeout must not alert everyone twice.\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Send or schedule an alert","description":"Without `scheduled_at`, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in `pending` (or already `dispatched` when nobody is waiting), and `GET` it to follow the send. With `scheduled_at` (ISO 8601, inside the window the preview's `schedule` reports), the alert is stored as `scheduled` and sent by the system at that time, after the same balance check. Send an `Idempotency-Key`: a retry after a timeout must not alert everyone twice.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /establishments/{establishment}/items/{item}/events","href":"/api/reference/dispatches/send-or-schedule-an-alert","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"v1.establishments.items.events.store","description":"Without `scheduled_at`, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in `pending` (or already `dispatched` when nobody is waiting), and `GET` it to follow the send. With `scheduled_at` (ISO 8601, inside the window the preview's `schedule` reports), the alert is stored as `scheduled` and sent by the system at that time, after the same balance check. Send an `Idempotency-Key`: a retry after a timeout must not alert everyone twice.","summary":"Send or schedule an alert","tags":["Dispatches"],"parameters":["b4a10449-d177-4def-96e6-ed1e4a62d920","155b1b6a-5617-4057-9f83-8c89905943c1","bbebcec0-2f2d-4be1-b5a8-e3d721b89338","62a5156e-0496-419a-bff9-a1788ae1e65d","61986aee-a670-43ae-9677-52f02c5adc98"],"requestBody":"6fb6736e-cf6e-40fb-ba2c-184a1cb912fd","responses":{"201":"a468edc0-da4f-41af-a0b8-a146d4b1e9ce","401":"91aa46f7-7239-4f1e-9f90-ea8c64e4cc48","403":"9d615b5f-1fd9-42f8-a8bd-4b4ce1649838","404":"a240b0e0-fcb0-4b0e-aecf-5b4f467e2ae0","409":"315d2072-cb95-49ac-9e1a-8a685a8a6887","422":"28b1ae64-3669-45d1-8751-a7119412ddec","429":"0b52fd0b-4e03-4e9d-a769-caeb55f0dcbb"},"method":"post","type":"path","servers":["4881b565-21c9-481f-ab04-2e9faf758340"],"security":["bba8f998-d38f-418f-a418-f9c23b32760a"],"path":"/establishments/{establishment}/items/{item}/events","baseUrlOptions":["https://needalert.app/api/v1"],"title":"Send or schedule an alert","codeSamples":[],"requestExampleLanguages":["bash","javascript","python","php"],"requiredOnlyExamples":true,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"b4a10449-d177-4def-96e6-ed1e4a62d920":{"name":"establishment","in":"path","required":true,"description":"The establishment ID","schema":{"type":"integer","isRequired":true,"description":"The establishment ID","uniqueKey":"","typeLabel":"integer"}},"155b1b6a-5617-4057-9f83-8c89905943c1":{"name":"item","in":"path","required":true,"description":"The item ID","schema":{"type":"integer","isRequired":true,"description":"The item ID","uniqueKey":"","typeLabel":"integer"}},"bbebcec0-2f2d-4be1-b5a8-e3d721b89338":{"name":"Idempotency-Key","in":"header","description":"Makes the request safe to retry. Send a value unique to this intended operation — a UUID v4 is recommended. The first response, a success **or** a business-rule refusal (any error with its own `code`, including `dispatch_in_progress` and `dispatch_too_soon`), is stored for 24 hours and replayed to a repetition with the same key and body, byte for byte and with its original `Content-Language`, under `Idempotent-Replayed: true`. A stored refusal is not retried: to try again for real, send a new key. `validation_failed`, `forbidden` and server errors are not stored. The same key with a different body is a 422 `idempotency_key_reused`; a repetition while the first request still runs is a 409 `idempotency_request_in_progress`. A replay counts towards the rate limit.","schema":{"type":"string","pattern":"^[\\x21-\\x7E]{1,255}$","minLength":1,"maxLength":255,"description":"Makes the request safe to retry. Send a value unique to this intended operation — a UUID v4 is recommended. The first response, a success **or** a business-rule refusal (any error with its own `code`, including `dispatch_in_progress` and `dispatch_too_soon`), is stored for 24 hours and replayed to a repetition with the same key and body, byte for byte and with its original `Content-Language`, under `Idempotent-Replayed: true`. A stored refusal is not retried: to try again for real, send a new key. `validation_failed`, `forbidden` and server errors are not stored. The same key with a different body is a 422 `idempotency_key_reused`; a repetition while the first request still runs is a 409 `idempotency_request_in_progress`. A replay counts towards the rate limit.","uniqueKey":"","typeLabel":"string"},"example":"7f0c4e3a-5b7e-4a8e-9f1c-2d3e4f5a6b7c"},"62a5156e-0496-419a-bff9-a1788ae1e65d":{"name":"Accept-Language","in":"header","description":"Language of `message` and of translated content such as item names (`pt-BR` or `en`). Without it, the chain's default language.","schema":{"type":"string","enum":["pt-BR","en"],"description":"Language of `message` and of translated content such as item names (`pt-BR` or `en`). Without it, the chain's default language.","uniqueKey":"","typeLabel":"enum\u003cstring>"},"example":"pt-BR"},"61986aee-a670-43ae-9677-52f02c5adc98":{"name":"X-Request-Id","in":"header","description":"Your own correlation id (1–64 characters of `A-Za-z0-9._-`), echoed back; generated when absent. Quote it to support.","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$","minLength":1,"maxLength":64,"description":"Your own correlation id (1–64 characters of `A-Za-z0-9._-`), echoed back; generated when absent. Quote it to support.","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":200,"isRequired":true,"uniqueKey":"message","typeLabel":"string"},"title":{"oneOf":[{"type":"string","maxLength":120,"uniqueKey":"title.oneOf.0","typeLabel":"string"},{"type":"null","maxLength":120,"uniqueKey":"title.oneOf.1","typeLabel":"null"}],"uniqueKey":"title","typeLabel":"string | null"},"scheduled_at":{"oneOf":[{"type":"string","format":"date-time","uniqueKey":"scheduled_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","uniqueKey":"scheduled_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"scheduled_at","typeLabel":"string\u003cdate-time> | null"}},"required":["message"],"title":"DispatchEventRequest","uniqueKey":"","typeLabel":"DispatchEventRequest · object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>","title":"\u003cstring>","scheduled_at":"2023-11-07T05:31:56Z"}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"a468edc0-da4f-41af-a0b8-a146d4b1e9ce":{"description":"`Event`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"integer","isRequired":true,"uniqueKey":"data.id","typeLabel":"integer"},"item":{"type":"object","properties":{"id":{"type":"integer","isRequired":true,"uniqueKey":"data.item.id","typeLabel":"integer"},"public_code":{"type":"string","isRequired":true,"uniqueKey":"data.item.public_code","typeLabel":"string"},"name":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"data.item.name.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"data.item.name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.item.name","typeLabel":"string | null"}},"required":["id","public_code","name"],"isRequired":true,"uniqueKey":"data.item","typeLabel":"object"},"title":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"data.title.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"data.title.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.title","typeLabel":"string | null"},"message":{"type":"string","isRequired":true,"uniqueKey":"data.message","typeLabel":"string"},"status":{"type":"string","description":"| |\n|---|\n| `pending` \u003cbr/> Queued to be sent now. |\n| `processing` \u003cbr/> Being sent. |\n| `dispatched` \u003cbr/> Sent; see `sent_count` and `failed_count`. |\n| `failed` \u003cbr/> Not sent; see `failure_reason`. |\n| `cancelled` \u003cbr/> Cancelled while scheduled. |\n| `scheduled` \u003cbr/> Waiting for `scheduled_at`. |","enum":["pending","processing","dispatched","failed","cancelled","scheduled"],"title":"EventStatus","isRequired":true,"uniqueKey":"data.status","typeLabel":"enum\u003cstring>"},"scheduled_at":{"oneOf":[{"type":"string","description":"When the alert is or was due; `null` for an immediate send.","isRequired":true,"uniqueKey":"data.scheduled_at.oneOf.0","typeLabel":"string"},{"type":"null","description":"When the alert is or was due; `null` for an immediate send.","isRequired":true,"uniqueKey":"data.scheduled_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.scheduled_at","typeLabel":"string | null"},"dispatched_at":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"data.dispatched_at.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"data.dispatched_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.dispatched_at","typeLabel":"string | null"},"recipients_count":{"type":"integer","description":"Subscribers the alert was sent to.","isRequired":true,"uniqueKey":"data.recipients_count","typeLabel":"integer"},"credits_cost":{"type":"integer","description":"Credits debited: one per recipient.","isRequired":true,"uniqueKey":"data.credits_cost","typeLabel":"integer"},"sent_count":{"type":"integer","isRequired":true,"uniqueKey":"data.sent_count","typeLabel":"integer"},"failed_count":{"type":"integer","isRequired":true,"uniqueKey":"data.failed_count","typeLabel":"integer"},"failure_reason":{"oneOf":[{"type":"string","title":"EventFailureReason","description":"| |\n|---|\n| `processing_error` \u003cbr/> An error while sending; the credits were not debited. |\n| `insufficient_credits` \u003cbr/> The balance did not cover the send when it was due. |\n| `missed_schedule` \u003cbr/> The scheduled time passed while the system was unavailable. |\n| `item_not_dispatchable` \u003cbr/> The item, unit or chain could no longer be alerted when the send was due. |","enum":["processing_error","insufficient_credits","missed_schedule","item_not_dispatchable"],"isRequired":true,"uniqueKey":"data.failure_reason.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","isRequired":true,"uniqueKey":"data.failure_reason.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.failure_reason","typeLabel":"enum\u003cstring> | null"},"estimated_credits_cost":{"oneOf":[{"type":"integer","description":"Scheduled alerts only: the cost estimated when the alert was scheduled or last rescheduled.","isRequired":true,"uniqueKey":"data.estimated_credits_cost.oneOf.0","typeLabel":"integer"},{"type":"null","description":"Scheduled alerts only: the cost estimated when the alert was scheduled or last rescheduled.","isRequired":true,"uniqueKey":"data.estimated_credits_cost.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.estimated_credits_cost","typeLabel":"integer | null"},"warning_sent_at":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"data.warning_sent_at.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"data.warning_sent_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.warning_sent_at","typeLabel":"string | null"},"cancelled_at":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"data.cancelled_at.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"data.cancelled_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.cancelled_at","typeLabel":"string | null"},"cancelled_by":{"oneOf":[{"type":"object","description":"The person who cancelled; `null` when an API key did or the alert was not cancelled.","properties":{"id":{"type":"integer","isRequired":true,"uniqueKey":"data.cancelled_by.oneOf.0.id","typeLabel":"integer"},"name":{"type":"string","isRequired":true,"uniqueKey":"data.cancelled_by.oneOf.0.name","typeLabel":"string"}},"required":["id","name"],"isRequired":true,"uniqueKey":"data.cancelled_by.oneOf.0","typeLabel":"object"},{"type":"null","description":"The person who cancelled; `null` when an API key did or the alert was not cancelled.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"isRequired":true,"uniqueKey":"data.cancelled_by.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.cancelled_by","typeLabel":"object | null"},"cancelled_by_api_client":{"oneOf":[{"type":"object","description":"The API key that cancelled; `null` when a person did or the alert was not cancelled.","properties":{"id":{"type":"integer","isRequired":true,"uniqueKey":"data.cancelled_by_api_client.oneOf.0.id","typeLabel":"integer"},"name":{"type":"string","isRequired":true,"uniqueKey":"data.cancelled_by_api_client.oneOf.0.name","typeLabel":"string"}},"required":["id","name"],"isRequired":true,"uniqueKey":"data.cancelled_by_api_client.oneOf.0","typeLabel":"object"},{"type":"null","description":"The API key that cancelled; `null` when a person did or the alert was not cancelled.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"isRequired":true,"uniqueKey":"data.cancelled_by_api_client.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.cancelled_by_api_client","typeLabel":"object | null"},"created_by":{"oneOf":[{"type":"object","description":"The person who created the alert; `null` when an API key or the system did.","properties":{"id":{"type":"integer","isRequired":true,"uniqueKey":"data.created_by.oneOf.0.id","typeLabel":"integer"},"name":{"type":"string","isRequired":true,"uniqueKey":"data.created_by.oneOf.0.name","typeLabel":"string"}},"required":["id","name"],"isRequired":true,"uniqueKey":"data.created_by.oneOf.0","typeLabel":"object"},{"type":"null","description":"The person who created the alert; `null` when an API key or the system did.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"isRequired":true,"uniqueKey":"data.created_by.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.created_by","typeLabel":"object | null"},"created_by_api_client":{"oneOf":[{"type":"object","description":"The API key that created the alert; `null` when a person did.","properties":{"id":{"type":"integer","isRequired":true,"uniqueKey":"data.created_by_api_client.oneOf.0.id","typeLabel":"integer"},"name":{"type":"string","isRequired":true,"uniqueKey":"data.created_by_api_client.oneOf.0.name","typeLabel":"string"}},"required":["id","name"],"isRequired":true,"uniqueKey":"data.created_by_api_client.oneOf.0","typeLabel":"object"},{"type":"null","description":"The API key that created the alert; `null` when a person did.","properties":{"id":{"type":"integer"},"name":{"type":"string"}},"required":["id","name"],"isRequired":true,"uniqueKey":"data.created_by_api_client.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.created_by_api_client","typeLabel":"object | null"},"created_at":{"oneOf":[{"type":"string","isRequired":true,"uniqueKey":"data.created_at.oneOf.0","typeLabel":"string"},{"type":"null","isRequired":true,"uniqueKey":"data.created_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"data.created_at","typeLabel":"string | null"},"notifications":{"type":"object","description":"Only on `GET …/events/{event}`: recipients per delivery status.","additionalProperties":{"type":"integer","uniqueKey":"data.notifications.additionalProperties","typeLabel":"integer"},"uniqueKey":"data.notifications","typeLabel":"object"}},"required":["id","item","title","message","status","scheduled_at","dispatched_at","recipients_count","credits_cost","sent_count","failed_count","failure_reason","estimated_credits_cost","warning_sent_at","cancelled_at","cancelled_by","cancelled_by_api_client","created_by","created_by_api_client","created_at"],"title":"Event","isRequired":true,"uniqueKey":"data","typeLabel":"Event · object"}},"required":["data"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"data":{"id":123,"item":{"id":123,"public_code":"\u003cstring>","name":"\u003cstring>"},"title":"\u003cstring>","message":"\u003cstring>","status":"pending","scheduled_at":"\u003cstring>","dispatched_at":"\u003cstring>","recipients_count":123,"credits_cost":123,"sent_count":123,"failed_count":123,"failure_reason":"processing_error","estimated_credits_cost":123,"warning_sent_at":"\u003cstring>","cancelled_at":"\u003cstring>","cancelled_by":{"id":123,"name":"\u003cstring>"},"cancelled_by_api_client":{"id":123,"name":"\u003cstring>"},"created_by":{"id":123,"name":"\u003cstring>"},"created_by_api_client":{"id":123,"name":"\u003cstring>"},"created_at":"\u003cstring>","notifications":{}}}}},"exampleType":"generated"}},"headers":{"Idempotent-Replayed":{"description":"Present, as `true`, when this is the stored response of an earlier request with the same `Idempotency-Key`.","schema":{"type":"string","enum":["true"]}},"Content-Language":{"description":"The language of the body, BCP 47 (`pt-BR`, `en`).","schema":{"type":"string"}},"X-Request-Id":{"description":"The request id, yours or the one generated here.","schema":{"type":"string"}}},"exampleType":"generated"},"91aa46f7-7239-4f1e-9f90-ea8c64e4cc48":{"description":"- `unauthenticated`: Missing, malformed, expired or revoked API key.","content":{"application/json":{"schema":{"type":"object","title":"ErrorEnvelope","description":"The shape of every error response of the API.","required":["message","code"],"properties":{"message":{"type":"string","description":"Translated (see `Content-Language`), for display only. Never program against it.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","description":"Stable `snake_case` identifier of the error. Program against it.","enum":["unauthenticated"],"isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"errors":{"type":"object","description":"Only on some errors: the invalid fields of a `validation_failed`, or extra data of a business-rule refusal.","uniqueKey":"errors","typeLabel":"object"}},"uniqueKey":"","typeLabel":"ErrorEnvelope · object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>","code":"unauthenticated","errors":{}}}},"exampleType":"generated"}},"headers":{"Content-Language":{"description":"The language of the body, BCP 47 (`pt-BR`, `en`).","schema":{"type":"string"}},"X-Request-Id":{"description":"The request id, yours or the one generated here.","schema":{"type":"string"}}},"exampleType":"generated"},"9d615b5f-1fd9-42f8-a8bd-4b4ce1649838":{"description":"- `establishment_unavailable`: The unit is inactive or suspended.\n- `forbidden`: The key lacks the permission this operation needs in this unit (`view`, `create_items`, `edit_items`, `dispatch_events` or `manage_billing`).\n- `tenant_suspended`: The chain that owns the key is suspended.","content":{"application/json":{"schema":{"type":"object","title":"ErrorEnvelope","description":"The shape of every error response of the API.","required":["message","code"],"properties":{"message":{"type":"string","description":"Translated (see `Content-Language`), for display only. Never program against it.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","description":"Stable `snake_case` identifier of the error. Program against it.","enum":["establishment_unavailable","forbidden","tenant_suspended"],"isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"errors":{"type":"object","description":"Only on some errors: the invalid fields of a `validation_failed`, or extra data of a business-rule refusal.","uniqueKey":"errors","typeLabel":"object"}},"uniqueKey":"","typeLabel":"ErrorEnvelope · object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>","code":"establishment_unavailable","errors":{}}}},"exampleType":"generated"}},"headers":{"Content-Language":{"description":"The language of the body, BCP 47 (`pt-BR`, `en`).","schema":{"type":"string"}},"X-Request-Id":{"description":"The request id, yours or the one generated here.","schema":{"type":"string"}}},"exampleType":"generated"},"a240b0e0-fcb0-4b0e-aecf-5b4f467e2ae0":{"description":"- `not_found`: No such resource, or it is outside the key's scope. The API never reveals whether a resource you cannot see exists.","content":{"application/json":{"schema":{"type":"object","title":"ErrorEnvelope","description":"The shape of every error response of the API.","required":["message","code"],"properties":{"message":{"type":"string","description":"Translated (see `Content-Language`), for display only. Never program against it.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","description":"Stable `snake_case` identifier of the error. Program against it.","enum":["not_found"],"isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"errors":{"type":"object","description":"Only on some errors: the invalid fields of a `validation_failed`, or extra data of a business-rule refusal.","uniqueKey":"errors","typeLabel":"object"}},"uniqueKey":"","typeLabel":"ErrorEnvelope · object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>","code":"not_found","errors":{}}}},"exampleType":"generated"}},"headers":{"Content-Language":{"description":"The language of the body, BCP 47 (`pt-BR`, `en`).","schema":{"type":"string"}},"X-Request-Id":{"description":"The request id, yours or the one generated here.","schema":{"type":"string"}}},"exampleType":"generated"},"315d2072-cb95-49ac-9e1a-8a685a8a6887":{"description":"- `idempotency_request_in_progress`: A request with this Idempotency-Key is still being processed. Try again in a moment.","content":{"application/json":{"schema":{"type":"object","title":"ErrorEnvelope","description":"The shape of every error response of the API.","required":["message","code"],"properties":{"message":{"type":"string","description":"Translated (see `Content-Language`), for display only. Never program against it.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","description":"Stable `snake_case` identifier of the error. Program against it.","enum":["idempotency_request_in_progress"],"isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"errors":{"type":"object","description":"Only on some errors: the invalid fields of a `validation_failed`, or extra data of a business-rule refusal.","uniqueKey":"errors","typeLabel":"object"}},"uniqueKey":"","typeLabel":"ErrorEnvelope · object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>","code":"idempotency_request_in_progress","errors":{}}}},"exampleType":"generated"}},"headers":{"Content-Language":{"description":"The language of the body, BCP 47 (`pt-BR`, `en`).","schema":{"type":"string"}},"X-Request-Id":{"description":"The request id, yours or the one generated here.","schema":{"type":"string"}}},"exampleType":"generated"},"28b1ae64-3669-45d1-8751-a7119412ddec":{"description":"- `dispatch_in_progress`: A dispatch for this item is already in progress.\n- `dispatch_too_soon`: Wait a few seconds before dispatching this item again.\n- `idempotency_key_reused`: This Idempotency-Key was already used for a different request.\n- `insufficient_credits`: Insufficient credit balance for this dispatch. `errors`: `required` (integer), `available` (integer).\n- `item_not_dispatchable`: This item cannot be dispatched right now.\n- `schedule_slot_taken`: There is already a dispatch scheduled for this item at this minute.\n- `validation_failed`: Invalid input. `errors`: each invalid field mapped to its messages.","content":{"application/json":{"schema":{"type":"object","title":"ErrorEnvelope","description":"The shape of every error response of the API.","required":["message","code"],"properties":{"message":{"type":"string","description":"Translated (see `Content-Language`), for display only. Never program against it.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","description":"Stable `snake_case` identifier of the error. Program against it.","enum":["dispatch_in_progress","dispatch_too_soon","idempotency_key_reused","insufficient_credits","item_not_dispatchable","schedule_slot_taken","validation_failed"],"isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"errors":{"type":"object","description":"Only on some errors: the invalid fields of a `validation_failed`, or extra data of a business-rule refusal.","uniqueKey":"errors","typeLabel":"object"}},"uniqueKey":"","typeLabel":"ErrorEnvelope · object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>","code":"dispatch_in_progress","errors":{}}}},"exampleType":"generated"}},"headers":{"Content-Language":{"description":"The language of the body, BCP 47 (`pt-BR`, `en`).","schema":{"type":"string"}},"X-Request-Id":{"description":"The request id, yours or the one generated here.","schema":{"type":"string"}}},"exampleType":"generated"},"0b52fd0b-4e03-4e9d-a769-caeb55f0dcbb":{"description":"- `too_many_requests`: Over the key's budget of 300 requests per minute, or over the 60 alert dispatches per minute of this route. Wait the seconds in `Retry-After`. The dispatch budget counts every attempt on this route, including ones later refused with 404, 403 or 422. The `X-RateLimit-*` headers of any response here, a successful one included, report the budget with fewer requests left, normally the dispatch one.","content":{"application/json":{"schema":{"type":"object","title":"ErrorEnvelope","description":"The shape of every error response of the API.","required":["message","code"],"properties":{"message":{"type":"string","description":"Translated (see `Content-Language`), for display only. Never program against it.","isRequired":true,"uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","description":"Stable `snake_case` identifier of the error. Program against it.","enum":["too_many_requests"],"isRequired":true,"uniqueKey":"code","typeLabel":"enum\u003cstring>"},"errors":{"type":"object","description":"Only on some errors: the invalid fields of a `validation_failed`, or extra data of a business-rule refusal.","uniqueKey":"errors","typeLabel":"object"}},"uniqueKey":"","typeLabel":"ErrorEnvelope · object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>","code":"too_many_requests","errors":{}}}},"exampleType":"generated"}},"headers":{"Retry-After":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per minute.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"Content-Language":{"description":"The language of the body, BCP 47 (`pt-BR`, `en`).","schema":{"type":"string"}},"X-Request-Id":{"description":"The request id, yours or the one generated here.","schema":{"type":"string"}}},"exampleType":"generated"}},"security":{"bba8f998-d38f-418f-a418-f9c23b32760a":{"apiKey":{"type":"http","description":"An API key created by the chain owner in the panel (**Integrações** → **Nova chave**), sent as `Authorization: Bearer \u003ckey>`. The key (`\u003cid>|na_…`) is shown once, at creation; rotate or revoke it on the same screen. It is a server secret: never ship it in browser or mobile code.","scheme":"bearer","scopes":[],"schemeName":"apiKey"}}},"servers":{"4881b565-21c9-481f-ab04-2e9faf758340":{"url":"https://needalert.app/api/v1","description":"Production"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","description":"An API key created by the chain owner in the panel (**Integrações** → **Nova chave**), sent as `Authorization: Bearer \u003ckey>`. The key (`\u003cid>|na_…`) is shown once, at creation; rotate or revoke it on the same screen. It is a server secret: never ship it in browser or mobile code.","scheme":"bearer","scopes":[],"schemeName":"apiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"An API key created by the chain owner in the panel (**Integrações** → **Nova chave**), sent as `Authorization: Bearer \u003ckey>`. The key (`\u003cid>|na_…`) is shown once, at creation; rotate or revoke it on the same screen. It is a server secret: never ship it in browser or mobile code.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"apiKey","name":"Authorization"}],"title":"apiKey"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"need-alert","siteName":"Need Alert","title":"Send or schedule an alert - Need Alert","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{"pt-BR":{"href":"/api/reference/dispatches/send-or-schedule-an-alert","matchLevel":0},"en":{"href":"/en/api/reference/dispatches/send-or-schedule-an-alert","matchLevel":1}}},"lastModified":"2026-10-19T04:16:33.244Z","originalFileLocation":"api/reference/dispatches/send-or-schedule-an-alert.mdx","locale":"pt-BR"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Without scheduled_at, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in pending (or already dispatched when nobody is waiting), and GET it to follow the send. With scheduled_at (ISO 8601, inside the window the preview\u0026#x27;s schedule reports), the alert is stored as scheduled and sent by the system at that time, after the same balance check. Send an Idempotency-Key: a retry after a timeout must not alert everyone twice.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Need Alert\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Send or schedule an alert - Need Alert\">\u003cmeta data-mint-head property=\"og:description\" content=\"Without scheduled_at, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in pending (or already dispatched when nobody is waiting), and GET it to follow the send. With scheduled_at (ISO 8601, inside the window the preview\u0026#x27;s schedule reports), the alert is stored as scheduled and sent by the system at that time, after the same balance check. Send an Idempotency-Key: a retry after a timeout must not alert everyone twice.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Need Alert\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://need-alert.mintlify.site/_mintlify/api/og/v2?division=Dispatches\u0026amp;title=Send+or+schedule+an+alert\u0026amp;description=Without+%60scheduled_at%60%2C+notifies+every+eligible+subscriber+of+the+item+now%2C+debiting+one+credit+per+person+after+checking+the+balance%3B+the+response+is+the+dispa\u0026amp;theme=bdfac1a245537d76f0edd834\u0026amp;signature=414e83d8cfce77b59daf5a2d939f0a43d4c4739ea3c69a4893b31de0127d9c37\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Send or schedule an alert - Need Alert\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Without scheduled_at, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in pending (or already dispatched when nobody is waiting), and GET it to follow the send. With scheduled_at (ISO 8601, inside the window the preview\u0026#x27;s schedule reports), the alert is stored as scheduled and sent by the system at that time, after the same balance check. Send an Idempotency-Key: a retry after a timeout must not alert everyone twice.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://need-alert.mintlify.site/_mintlify/api/og/v2?division=Dispatches\u0026amp;title=Send+or+schedule+an+alert\u0026amp;description=Without+%60scheduled_at%60%2C+notifies+every+eligible+subscriber+of+the+item+now%2C+debiting+one+credit+per+person+after+checking+the+balance%3B+the+response+is+the+dispa\u0026amp;theme=bdfac1a245537d76f0edd834\u0026amp;signature=414e83d8cfce77b59daf5a2d939f0a43d4c4739ea3c69a4893b31de0127d9c37\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/need-alert/RuPQ-F31d7vVQjKt/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Need Alert\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#465FFF\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api/reference/dispatches/send-or-schedule-an-alert.md\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"pt-BR\" href=\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"en\" href=\"https://docs.needalert.app/en/api/reference/dispatches/send-or-schedule-an-alert\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"x-default\" href=\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.needalert.app/#organization\",\"name\":\"Need Alert\",\"url\":\"https://docs.needalert.app\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/need-alert/9mmUrKHe_2MF526d/logo/light.svg?fit=max\u0026auto=format\u0026n=9mmUrKHe_2MF526d\u0026q=85\u0026s=373a6fb813b58847213edb4a69e07fc2\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.needalert.app#website\",\"name\":\"Need Alert\",\"url\":\"https://docs.needalert.app\",\"publisher\":{\"@id\":\"https://docs.needalert.app/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert#webpage\",\"url\":\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert\",\"name\":\"Send or schedule an alert\",\"description\":\"Without scheduled_at, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in pending (or already dispatched when nobody is waiting), and GET it to follow the send. With scheduled_at (ISO 8601, inside the window the preview's schedule reports), the alert is stored as scheduled and sent by the system at that time, after the same balance check. Send an Idempotency-Key: a retry after a timeout must not alert everyone twice.\",\"dateModified\":\"2026-10-19T04:16:33.244Z\",\"isPartOf\":{\"@id\":\"https://docs.needalert.app#website\"},\"breadcrumb\":{\"@id\":\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.needalert.app/api/reference/establishments/list-units\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Dispatches\",\"item\":\"https://docs.needalert.app/api/reference/dispatches/preview-an-alert\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Send or schedule an alert\",\"item\":\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert#apireference\",\"headline\":\"Send or schedule an alert\",\"name\":\"Send or schedule an alert\",\"description\":\"Without scheduled_at, notifies every eligible subscriber of the item now, debiting one credit per person after checking the balance; the response is the dispatch in pending (or already dispatched when nobody is waiting), and GET it to follow the send. With scheduled_at (ISO 8601, inside the window the preview's schedule reports), the alert is stored as scheduled and sent by the system at that time, after the same balance check. Send an Idempotency-Key: a retry after a timeout must not alert everyone twice.\",\"url\":\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert\",\"mainEntityOfPage\":{\"@id\":\"https://docs.needalert.app/api/reference/dispatches/send-or-schedule-an-alert#webpage\"},\"dateModified\":\"2026-10-19T04:16:33.244Z\",\"publisher\":{\"@id\":\"https://docs.needalert.app/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.needalert.app#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Need Alert\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Need Alert\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api/reference/dispatches/send-or-schedule-an-alert.md","siteName":"Need Alert","nav":{"global":null,"languages":[{"language":"pt-BR","default":true,"tabs":[{"tab":"Guias","pages":[{"title":"Guias","href":""}]},{"tab":"API","groups":[{"group":"Introdução","pages":[{"title":"Visão geral da API","icon":"code","href":"/api/overview"},{"title":"Autenticação","icon":"key","href":"/api/authentication"},{"title":"Primeira requisição","icon":"rocket","href":"/api/first-request"}]},{"group":"Guias","pages":[{"title":"Idempotência","icon":"rotate","href":"/api/idempotency"},{"title":"Referência externa","icon":"barcode","href":"/api/external-reference"},{"title":"Casos de uso","icon":"diagram-project","href":"/api/use-cases"}]},{"group":"Convenções","pages":[{"title":"Convenções","icon":"book","href":"/api/conventions"},{"title":"Changelog","icon":"clock-rotate-left","href":"/api/changelog"}]},{"group":"Endpoints","pages":[{"group":"Establishments","pages":[{"title":"List units","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /establishments","href":"/api/reference/establishments/list-units"},{"title":"Get a unit","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /establishments/{establishment}","href":"/api/reference/establishments/get-a-unit"}]},{"group":"Items","pages":[{"title":"List items","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /establishments/{establishment}/items","href":"/api/reference/items/list-items"},{"title":"Create an item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /establishments/{establishment}/items","href":"/api/reference/items/create-an-item"},{"title":"Get an item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /establishments/{establishment}/items/{item}","href":"/api/reference/items/get-an-item"},{"title":"Archive an item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /establishments/{establishment}/items/{item}","href":"/api/reference/items/archive-an-item"},{"title":"Update an item","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /establishments/{establishment}/items/{item}","href":"/api/reference/items/update-an-item"},{"title":"Get the item's QR code","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /establishments/{establishment}/items/{item}/qr-code","href":"/api/reference/items/get-the-items-qr-code"},{"title":"Upload the item's picture","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /establishments/{establishment}/items/{item}/image","href":"/api/reference/items/upload-the-items-picture"},{"title":"Remove the item's picture","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /establishments/{establishment}/items/{item}/image","href":"/api/reference/items/remove-the-items-picture"}]},{"group":"Dispatches","pages":[{"title":"Preview an alert","description":"What sending this item's alert right now would cost: eligible subscribers, credits (one per person), the chain's balance and whether it covers the send. Nothing is sent or charged. `schedule` gives the window `scheduled_at` accepts and the lead of the low-balance warning.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /establishments/{establishment}/items/{item}/dispatch-preview","href":"/api/reference/dispatches/preview-an-alert"},{"title":"Send or schedule an alert","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /establishments/{establishment}/items/{item}/events","href":"/api/reference/dispatches/send-or-schedule-an-alert"},{"title":"List dispatches","description":"The unit's alerts, newest first, paginated. Filter by `item_id` and `status`.","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /establishments/{establishment}/events","href":"/api/reference/dispatches/list-dispatches"},{"title":"Get a dispatch","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /establishments/{establishment}/events/{event}","href":"/api/reference/dispatches/get-a-dispatch"},{"title":"Cancel a scheduled dispatch","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json delete /establishments/{establishment}/events/{event}","href":"/api/reference/dispatches/cancel-a-scheduled-dispatch"},{"title":"Reschedule a dispatch","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json patch /establishments/{establishment}/events/{event}","href":"/api/reference/dispatches/reschedule-a-dispatch"}]},{"group":"Credits","pages":[{"title":"Get the credit balance","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /tenants/{tenant}/credit-balance","href":"/api/reference/credits/get-the-credit-balance"},{"title":"List credit transactions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /tenants/{tenant}/credit-transactions","href":"/api/reference/credits/list-credit-transactions"}]}]}]}]},{"language":"en","pages":[{"title":"en","href":"/en/api/reference/dispatches/send-or-schedule-an-alert"}]}]},"basePath":"","title":"Send or schedule an alert - Need Alert","buildId":"dpl_DqYu5MPb49gWBBbUGgpHQUmCHY3P","deploymentId":"dpl_DqYu5MPb49gWBBbUGgpHQUmCHY3P","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CybtLBIt.js","utils-BMLj2fvV.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-B6In562Y.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-Dr8Mfhp9.js","snippetPresets-2rmQvMVl.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-WMqJYdZj.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-CJ-MlPHu.js","shallow-dY3TMRCk.js","getApiPlaygroundDisplay-v-1B2bKm.js","CodeSnippet-BDhiTB7U.js","CodeSnippets-D9hnzQcS.js","Page-C4GwDT3_.js","getPastedJson-Th2V45jI.js","icon-BQXch1W9.js","MethodPill-BCqUneP3.js","DuplicateIcon-Q_-bhurZ.js","createIcon-DUjLHRqp.js","DynamicMarkdown-B-f2cqXQ.js","SectionHeading-Da5NsV4v.js","axios-vUo_bRtp.js","Markdown-D13FWkIM.js","clsx-D3Isdib3.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-C-XZBk9h.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink--qIqmmVG.js"]}