> For the complete documentation index, see [llms.txt](https://help.recart.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.recart.com/developers/public-api/event/post-an-event.md). # Post an event Post an event which can be used to trigger flows in Recart. Three preconditions must hold, each of which fails with its own status code: * the event source (`source.category` and `source.name`) is registered for the site via `POST /event-sources`, * `phoneNumber` belongs to an existing subscriber — this endpoint never creates one, * that subscriber has an active SMS subscription. A newly registered event source does not become usable instantly. Allow a short delay after creating one before posting the first event against it, and expect the first events to be able to fail with `417` until it has propagated. Whether a flow is actually listening for the event is *not* checked. If no active Integration flow uses the event source as its trigger, the event is still accepted and simply results in no message — so confirm the flow is active in the Recart dashboard when events succeed but nothing is sent. The event is queued for processing, so `200` confirms that it was accepted, not that a message was sent. The `200` response body is the plain-text string `OK`, not a JSON:API document — do not parse it as JSON. ```json {"openapi":"3.1.0","info":{"title":"Recart API","version":"2023-12"},"tags":[{"name":"Event","description":"Events"}],"servers":[{"url":"https://api.recart.com/app-integrations/2023-12","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Recart-API-Key","description":"It can be obtained in Recart account after contacting Support"}},"schemas":{"PostEvent":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["events"]},"attributes":{"type":"object","required":["phoneNumber","source"],"properties":{"phoneNumber":{"type":"string","description":"Preferably E.164 format"},"source":{"type":"object","required":["category","name"],"properties":{"category":{"type":"string","description":"Source category"},"name":{"type":"string","description":"Source name"}}},"properties":{"type":"object","description":"Data of the event, as flat key/value pairs. At most 10 properties are\nallowed; more than that is rejected with `400`.\n\nProperties are not automatically available to the flow. Only properties that\nRecart already supports are delivered to messages, where the message inserts\none from the flow editor's variable picker. Contact Support to find out which\nproperties your account can use, or to request support for a new one.\n\nAny other property is accepted and then discarded. The request still returns\n`200` and the flow is still triggered, but the value never reaches the\nmessage, so a discarded property is indistinguishable from a delivered one.\nDo not design a message around a property you have not confirmed is\nsupported. To personalise or target on your own data, store it on the\nsubscriber with `PATCH /subscribers` and use it as a segment condition\ninstead.\n"}}}}},"HttpErrorBody":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["id","code","title","detail"],"properties":{"id":{"type":"string"},"code":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}}},"responses":{"HttpError":{"description":"HTTP Error response","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}}}},"paths":{"/events":{"post":{"summary":"Post an event","tags":["Event"],"operationId":"postEvent","description":"Post an event which can be used to trigger flows in Recart.\n\nThree preconditions must hold, each of which fails with its own status code:\n\n- the event source (`source.category` and `source.name`) is registered for the site\n via `POST /event-sources`,\n- `phoneNumber` belongs to an existing subscriber — this endpoint never creates one,\n- that subscriber has an active SMS subscription.\n\nA newly registered event source does not become usable instantly. Allow a short delay\nafter creating one before posting the first event against it, and expect the first\nevents to be able to fail with `417` until it has propagated.\n\nWhether a flow is actually listening for the event is *not* checked. If no active\nIntegration flow uses the event source as its trigger, the event is still accepted\nand simply results in no message — so confirm the flow is active in the Recart\ndashboard when events succeed but nothing is sent.\n\nThe event is queued for processing, so `200` confirms that it was accepted, not that\na message was sent. The `200` response body is the plain-text string `OK`, not a\nJSON:API document — do not parse it as JSON.\n","requestBody":{"required":true,"content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostEvent"}}}}}},"responses":{"200":{"description":"The event was accepted and queued for processing. The body is the plain-text\nstring `OK`.\n","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"`ERR_BAD_REQUEST` — the payload failed validation, in which case `detail` lists\nthe offending fields, or `phoneNumber` could not be parsed as a phone number.\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"401":{"description":"`ERR_UNAUTHORIZED` — the `X-Recart-API-Key` header is missing.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"403":{"description":"`ERR_FORBIDDEN` — the API key is unknown or has been revoked.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"404":{"description":"`ERR_NOT_FOUND` — no subscriber exists for `phoneNumber`. Subscribe the phone\nnumber first; posting an event does not create a subscriber.\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"415":{"description":"`ERR_UNSUPPORTED_MEDIA_TYPE` — `Content-Type` must be `application/vnd.api+json`\nor `application/json`.\n\nA `Content-Type` the API cannot parse at all is rejected earlier, before this\nerror format applies, and returns an unstructured plain-text body. A malformed\nJSON body is rejected the same way, with `400`.\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"417":{"description":"`ERR_EXPECTATION_FAILED` — a precondition on the account is not met. Either no\nevent source is registered for the site with this `source.category` and\n`source.name` pair, or the subscriber exists but does not have an active SMS\nsubscription. The two cases are distinguished by `detail`.\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"500":{"description":"`ERR_INTERNAL_SERVER_ERROR` — the event passed validation but the request could\nnot be processed, either because the subscriber could not be looked up or\nbecause the event could not be queued. The event was not processed, so it is\nsafe to retry.\n\nFailures reaching an upstream service can also surface as other `5XX` statuses\nwith an unstructured body, so treat the whole `5XX` range as retryable rather\nthan matching on `500` alone.\n","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/HttpErrorBody"}}}},"4XX":{"$ref":"#/components/responses/HttpError"},"5XX":{"$ref":"#/components/responses/HttpError"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.recart.com/developers/public-api/event/post-an-event.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.