Vic.ai Email Endpoints API

openapi: 3.2.0
info:
  version: v10.40.4
  contact: {}
  title: Vic.ai Email Endpoints API
  description: '## Introduction


    The Vic.ai API provides a seamless connection between your Enterprise Resource

    Planning (ERP) system and the Vic.ai product suite.'
servers:
- url: https://api.no.stage.vic.ai
  description: staging server, NO
- url: https://api.us.vic.ai
  description: production server, US
- url: https://api.no.vic.ai
  description: production server, NO
security:
- BearerAuth: []
tags:
- name: Email Endpoints
  description: 'Email endpoints are dedicated email addresses that Vic.ai monitors so

    your team can forward or send invoices, contracts, or receipts in by

    email. Each company can have multiple endpoints, each configured for a

    specific document type. Endpoints can optionally restrict which sender

    addresses are accepted; see the *Allowed Senders* endpoints.'
paths:
  /v2/companies/{company_id}/email_endpoints:
    get:
      description: Lists email endpoints for the company, newest first.
      summary: List email endpoints
      operationId: listEmailEndpointsV2
      tags:
      - Email Endpoints
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/PaginationV2'
      responses:
        '200':
          description: A page of email endpoints.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEndpointsResponseV2'
        '403':
          $ref: '#/components/responses/ErrorResponseV2'
        '404':
          $ref: '#/components/responses/ErrorResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
    post:
      description: 'Creates a new email endpoint. All request fields are optional;

        Vic.ai assigns a unique local-part and uses the company''s default

        domain when not specified.'
      summary: Create email endpoint
      operationId: createEmailEndpointV2
      tags:
      - Email Endpoints
      parameters:
      - name: company_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailEndpointWriteV2'
      responses:
        '201':
          description: The created email endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEndpointResponseV2'
        '403':
          $ref: '#/components/responses/ErrorResponseV2'
        '404':
          $ref: '#/components/responses/ErrorResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
  /v2/email_endpoints/{id}:
    get:
      description: Retrieves a single email endpoint by id.
      summary: Get email endpoint
      operationId: getEmailEndpointV2
      tags:
      - Email Endpoints
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The email endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEndpointResponseV2'
        '403':
          $ref: '#/components/responses/ErrorResponseV2'
        '404':
          $ref: '#/components/responses/ErrorResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
    patch:
      description: 'Updates an email endpoint. Only the fields supplied in the

        request body are changed; omitted fields are left as-is.'
      summary: Update email endpoint
      operationId: updateEmailEndpointV2
      tags:
      - Email Endpoints
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailEndpointWriteV2'
      responses:
        '200':
          description: The updated email endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEndpointResponseV2'
        '403':
          $ref: '#/components/responses/ErrorResponseV2'
        '404':
          $ref: '#/components/responses/ErrorResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
    delete:
      description: 'Permanently deletes an email endpoint. Returns an error if any

        emails have already been delivered through this endpoint.'
      summary: Delete email endpoint
      operationId: deleteEmailEndpointV2
      tags:
      - Email Endpoints
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: The email endpoint has been deleted.
        '403':
          $ref: '#/components/responses/ErrorResponseV2'
        '404':
          $ref: '#/components/responses/ErrorResponseV2'
        4XX:
          $ref: '#/components/responses/ErrorResponseV2'
components:
  schemas:
    EmailEndpointV2:
      type: object
      required:
      - id
      - address
      - document_type
      - gen_email_screenshot
      - created_at
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        address:
          type: string
          description: The full email address to send documents to.
        document_type:
          type: string
          enum:
          - contract
          - invoice
          - receipt
        gen_email_screenshot:
          type: boolean
          description: 'When `true`, Vic.ai captures a screenshot of the email body

            and attaches it to the document for review.

            '
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    EmailEndpointResponseV2:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/EmailEndpointV2'
    ErrorV2:
      type: object
      required:
      - message
      properties:
        field:
          description: 'The field that the error occurred on. This field may not always be

            present.

            '
          oneOf:
          - type: string
          - type: 'null'
        message:
          description: A description of the error.
          type: string
    EmailEndpointWriteV2:
      type: object
      description: 'Fields accepted on create and update. All fields are optional;

        omitted fields use defaults (on create) or retain their current

        value (on update).

        '
      properties:
        token:
          type: string
          description: 'The local-part of the endpoint address (the part before the

            `@`). Must be unique across the endpoint''s domain.

            '
        domain:
          type: string
          description: 'The domain of the endpoint address. Defaults to the

            company''s primary inbound domain.

            '
        document_type:
          type: string
          enum:
          - contract
          - invoice
          - receipt
        gen_email_screenshot:
          type: boolean
          description: 'When `true`, Vic.ai captures a screenshot of the email body

            and attaches it to the document for review.

            '
    EmailEndpointsResponseV2:
      type: object
      required:
      - meta
      - data
      properties:
        meta:
          type: object
          required:
          - page
          properties:
            page:
              $ref: '#/components/schemas/PaginationMetaV2'
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmailEndpointV2'
    PaginationMetaV2:
      type: object
      properties:
        cursor:
          description: 'The cursor to the next page of data. If it is null, that means there

            is no more data to fetch.

            '
          oneOf:
          - type: string
          - type: 'null'
    PaginationV2:
      type: object
      properties:
        size:
          type: integer
          description: The page size.
          maximum: 50
          minimum: 1
        cursor:
          type: string
          description: The cursor to use to get the next page of results.
  parameters:
    PaginationV2:
      name: page
      in: query
      schema:
        $ref: '#/components/schemas/PaginationV2'
  responses:
    ErrorResponseV2:
      description: An unexpected error has occurred. Check the body for more details.
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  $ref: '#/components/schemas/ErrorV2'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
x-tagGroups:
- name: Integration
  tags:
  - Authentication
  - Pagination
  - Webhooks
  - Webhook Subscriptions
  - Webhook Events
  - Synchronizing
  - Status
- name: Master Data
  tags:
  - Accounts
  - Dimensions
  - Vendors
  - Vendor Groups
  - Vendor Tags
  - Tags
  - Tax Codes
  - VAT Codes
  - Payment Terms
- name: Organization & Access
  tags:
  - Partners
  - Organizations
  - Companies
  - Users
- name: Invoices & Bills
  tags:
  - Invoices
  - Bills
  - Attachments
  - Invoice Approval Flows
  - Invoice Posting Guide
  - Training Invoices
- name: Purchase Orders
  tags:
  - Purchase Orders
  - Purchase Order Line Items
  - Purchase Order Matching Guide
- name: Payments
  tags:
  - Payment Batches
  - Payment Confirmations
  - Credit Confirmations
- name: Reporting
  tags:
  - CSV Reports
- name: Reference
  tags:
  - Changelog