sendraven-ai Events API

openapi: 3.2.0
info:
  title: Sendraven Ai Events API
  version: 1.0.0
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: sendraven-ai-api-openapi.json, sendraven-ai-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sendraven.ai
security:
- bearerAuth: []
tags:
- name: Events
paths:
  /v1/events:
    post:
      summary: Emit an event
      description: 'Enrols the address in every active automation whose trigger is event with event_name equal to name (exact, case-sensitive), just as enrolling directly would: each automation''s exits still apply and nobody is enrolled twice. One call from your app, such as trial_started, instead of it knowing which sequences exist. Events are not stored: one nothing waits for does nothing and is not an error, and an automation created later is not started by earlier events. Guardrails are checked before any automation is looked up: a key that holds its sends for approval cannot record events, and a key with a recipient allowlist only for addresses on it. The key''s daily cap is not checked. Check GET /v1/automations/{id} when automations_started is lower than expected. When name is a conversion goal (GET /v1/conversion-goals), the event is also recorded as a conversion and conversion_id is set; it is credited to an email a few seconds later, see GET /v1/conversions/{id}.'
      x-required-scope: emails:send
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - email
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: Matched exactly against each automation's trigger.event_name.
                email:
                  type: string
                  format: email
                  description: A single address. Trimmed.
                variables:
                  type: object
                  additionalProperties:
                    type: string
                  description: Passed to every enrolment this event starts. Every value must be a string.
                  default: {}
                id:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: Your own id for the event, such as an invoice id. When name is a conversion goal, a second event with the same id records nothing new and answers the first conversion's id. Ignored otherwise.
                value:
                  type: number
                  minimum: 0
                  description: What the conversion was worth, as a decimal (49.99). Requires currency. Ignored unless name is a conversion goal.
                currency:
                  type: string
                  pattern: ^[A-Za-z]{3}$
                  description: ISO 4217 code for value, such as USD. Stored upper case. Requires value.
      responses:
        '200':
          description: How many automations enrolled the person
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '400':
          description: 'invalid_json: the request body is not valid JSON.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'unauthorized: no Bearer token, or the key or token is invalid, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: the calling key holds its sends for approval. recipient_not_allowed: the key has a recipient allowlist and email is not on it. Also forbidden: the key lacks the emails:send scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'idempotency_in_progress: a request with the same Idempotency-Key was still running on this path after waiting up to 8 seconds for it (a retry that finds it finished receives its response instead). Retry after a short wait.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: 'payload_too_large: the body is larger than this endpoint accepts (5 MB unless stated).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: 'invalid_request: name or email is missing or invalid, variables is not an object of strings, or value and currency were not sent together. The message names each field that failed and details lists them. Also idempotency_key_reused: this Idempotency-Key was already used on this path with a different request body (checked right after the scope, so a credential without the scope gets 403 instead, and answered at once even while the first request is still running). Do not retry; send the new request under a new key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'rate_limited: more requests than the per-key rate (600 a minute by default). Wait the seconds in the Retry-After header and retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 'service_unavailable: the API is under heavy load and could not get a database connection in time. Usually nothing was done; a send that was already under way may have been, so check GET /v1/emails before retrying one. Wait the seconds in the Retry-After header.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type: string
        description: 'Replaying the same key on the same path in this workspace within 24 hours returns the stored response, with an Idempotent-Replay: true header, instead of acting again. Only successful responses are stored, so a failed request can be fixed and retried under the same key. The body is compared (key order ignored): the same key with a different body is 422 idempotency_key_reused, so use a new key for every new request. Use an unguessable value such as a UUID.'
      tags:
      - Events
      operationId: postV1Events
      x-operation-id-source: derived
    servers:
    - url: https://api.sendraven.ai
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - type
          - message
          properties:
            type:
              type: string
              description: 'Stable and safe to branch on, and the same status on every route: invalid_request (422), invalid_json (400), payload_too_large (413), unauthorized (401), forbidden (403), not_found (404), conflict (409, an identifier already taken), invalid_state (409, the resource''s current state does not allow this), plan_limit_reached (402), payment_method_required (402), billing_past_due (402), budget_exceeded (402), no_verified_identity (422), missing_variables (422), unknown_topic (422), idempotency_in_progress (409), idempotency_key_reused (422), approval_in_progress (409), rate_limited (429), daily_limit (429), recipient_not_allowed (403), invalid_schedule (422), warmup_limit (422), no_postal_address (422), workspace_suspended (422), gone (410), ses_error (502), internal_error (500), service_unavailable (503).'
            message:
              type: string
              description: For people; may change.
            details:
              type: array
              items:
                type: object
                additionalProperties: true
              description: 'On many 422 invalid_request answers: one entry per field that failed validation.'
            missing:
              type: array
              items:
                type: string
              description: 'Only on missing_variables, and always there: the names of the template variables that were not supplied.'
    EventResponse:
      type: object
      required:
      - event
      - automations_started
      - conversion_id
      properties:
        event:
          type: string
          description: The name as given.
        automations_started:
          type: integer
          minimum: 0
          description: Automations that actually enrolled the person. Exclusions, an existing active enrolment, or an automation that cannot enrol anyone are not reported, only left out of the count. 0 is not an error.
        conversion_id:
          type:
          - string
          - 'null'
          description: The conversion this event recorded, when name is a conversion goal; with a repeated id, the first one's. null when name is not a goal.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key of the form sk_live_…, created at /developers, or an OAuth access token (srv_oat_…). An OAuth token carries its grant's scopes but none of an API key's guardrails, and cannot decide approvals.
x-refined-from:
- sendraven-ai-api-openapi.json
- sendraven-ai-openapi.json