sendraven-ai Forwarding Addresses API

openapi: 3.2.0
info:
  title: Sendraven Ai Forwarding Addresses API
  version: 1.0.0
  description: 'Operations tagged Forwarding Addresses 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: Forwarding Addresses
paths:
  /v1/forwarding-addresses:
    get:
      summary: List forwarding addresses
      description: Pending and active forwarding addresses, newest first, cursor-paged. Removed addresses are not listed.
      x-required-scope: domains:read
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Page size. A larger value is capped at 100, a fraction is rounded down, and zero, a negative or a non-number falls back to 50. None of these is an error.
      - name: cursor
        in: query
        schema:
          type: string
        description: The next_cursor from the previous page, passed back unchanged. An unreadable cursor returns the first page.
      responses:
        '200':
          description: Forwarding addresses.
          content:
            application/json:
              schema:
                type: object
                required:
                - object
                - data
                - has_more
                - next_cursor
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ForwardingAddress'
                  has_more:
                    type: boolean
                    description: True when another page exists; pass next_cursor back as cursor.
                  next_cursor:
                    type:
                    - string
                    - 'null'
        '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 key lacks the domains:read scope. The message names it.'
          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'
      tags:
      - Forwarding Addresses
      operationId: getV1ForwardingAddresses
      x-operation-id-source: derived
    post:
      summary: Add a forwarding address, or resend its confirmation
      description: 'Emails a confirmation link to the address; nothing is forwarded until it is clicked. Posting an address that is already pending sends a new link (the old one stops working), at most once a minute and five times in all; posting one that is already active changes nothing and returns it with 200. Forwards are sent from the workspace''s verified transactional domain, with the original sender as Reply-To, through the normal send path (suppression and billing apply, and each copy counts as one email). Spam and virus FAIL verdicts, automated mail (bounces, out-of-office) and our own forwards are never forwarded. Requires a verified payment method. A workspace may add at most 10 distinct addresses over its life; removing one does not free a slot. Refused (403) for OAuth access tokens and for keys with guardrails: an agent credential must not be able to route a workspace''s mail to an inbox it reads.'
      x-required-scope: domains:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: The inbox to forward to. Not on a domain SendRaven receives mail for.
                inbound_domain:
                  type:
                  - string
                  - 'null'
                  description: Forward only mail received on this domain, one of the workspace's domains (GET /v1/domains). Omit or null for every domain. Ignored when the address already exists.
      responses:
        '200':
          description: 'Already existed: a pending address was sent a new confirmation, or an active one was returned unchanged.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardingAddress'
        '201':
          description: Added; the confirmation email is on its way.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardingAddress'
        '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'
        '402':
          description: 'payment_method_required: no verified payment method; a person must add one in the dashboard. plan_limit_reached: the workspace has added the most distinct forwarding addresses it may.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'forbidden: an OAuth access token, or a key with guardrails, cannot add forwarding addresses. Also forbidden: the key lacks the domains:write scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'invalid_state: this address has been sent all five confirmation emails it can be sent. Also 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: email missing or not an address, on a domain SendRaven receives mail for, or inbound_domain not one of the workspace''s domains. workspace_suspended: sending is suspended for the workspace. 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: a confirmation was sent to this address less than a minute ago. Retry-After gives the seconds. Also 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'
        '502':
          description: 'ses_error: the address was stored but the confirmation email could not be sent. POST it again after a minute.'
          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:
      - Forwarding Addresses
      operationId: postV1ForwardingAddresses
      x-operation-id-source: derived
    servers:
    - url: https://api.sendraven.ai
  /v1/forwarding-addresses/{id}:
    get:
      summary: Retrieve a forwarding address
      description: One pending or active forwarding address. Poll it to see when the confirmation was clicked.
      x-required-scope: domains:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The forwarding address's id from GET /v1/forwarding-addresses (a UUID), not the address itself.
      responses:
        '200':
          description: The forwarding address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForwardingAddress'
        '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 key lacks the domains:read scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: no pending or active forwarding address with this id ("No such forwarding address").'
          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'
      tags:
      - Forwarding Addresses
      operationId: getV1ForwardingAddressesById
      x-operation-id-source: derived
    delete:
      summary: Remove a forwarding address
      description: Stops forwarding to the address at once, and an unused confirmation link stops working. Adding it again needs a new confirmation. It still counts toward the workspace's lifetime limit.
      x-required-scope: domains:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The forwarding address's id from GET /v1/forwarding-addresses (a UUID), not the address itself.
      responses:
        '200':
          description: Removed.
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - deleted
                properties:
                  id:
                    type: string
                    format: uuid
                  deleted:
                    type: boolean
                    enum:
                    - true
        '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 key lacks the domains:write scope. The message names it.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'not_found: no pending or active forwarding address with this id ("No such forwarding address").'
          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'
      tags:
      - Forwarding Addresses
      operationId: deleteV1ForwardingAddressesById
      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.'
    ForwardingAddress:
      type: object
      description: An outside inbox that a copy of the workspace's received mail is forwarded to. Nothing is forwarded until the address is confirmed by clicking the link emailed to it. The confirmation token is never in any response.
      required:
      - id
      - email
      - status
      - inbound_domain
      - confirmation_sent_at
      - confirmation_expires_at
      - confirmed_at
      - created_at
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
          description: The destination, lower-cased.
        status:
          type: string
          enum:
          - pending
          - active
          description: pending until the confirmation link is clicked; only active addresses receive forwards.
        inbound_domain:
          type:
          - string
          - 'null'
          description: Forward only mail received on this domain. null forwards mail received on every domain.
        confirmation_sent_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the latest confirmation email was sent.
        confirmation_expires_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the latest confirmation link stops working (72 hours after it was sent). null once active.
        confirmed_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
  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