openapi: 3.1.0
info:
  title: Nylas API (v3)
  description: |
    Nylas provides unified APIs for email, calendar, contacts, and
    scheduling across many underlying providers (Google, Microsoft, IMAP,
    etc.). Resources are scoped to a grant that represents an end-user
    connection. Endpoint scaffold below is derived from the public v3
    developer documentation at https://developer.nylas.com/docs/.
  version: "3.0"
  contact:
    name: Nylas Developers
    url: https://developer.nylas.com
servers:
  - url: https://api.us.nylas.com
    description: United States region
  - url: https://api.eu.nylas.com
    description: European Union region
security:
  - BearerAuth: []
tags:
  - name: Auth
  - name: Grants
  - name: Messages
  - name: Threads
  - name: Drafts
  - name: Calendars
  - name: Events
  - name: Contacts
  - name: Scheduling
  - name: Admin
paths:
  /v3/connect/custom:
    post:
      tags: [Auth]
      summary: Create a custom authentication grant
      responses:
        '200':
          description: A grant has been created.
  /v3/connect/auth:
    get:
      tags: [Auth]
      summary: Begin hosted OAuth authentication
      responses:
        '302':
          description: Redirects to the configured authentication provider.
  /v3/connect/token:
    post:
      tags: [Auth]
      summary: Exchange an authorization code for tokens
      responses:
        '200':
          description: Returns access and refresh tokens.
  /v3/grants:
    get:
      tags: [Grants]
      summary: List grants
      responses:
        '200':
          description: A list of grants associated with the application.
  /v3/grants/{grant_id}:
    parameters:
      - in: path
        name: grant_id
        required: true
        schema:
          type: string
    get:
      tags: [Grants]
      summary: Retrieve a grant
      responses:
        '200':
          description: The grant record.
    delete:
      tags: [Grants]
      summary: Delete a grant
      responses:
        '200':
          description: The grant was deleted.
  /v3/grants/{grant_id}/messages:
    parameters:
      - in: path
        name: grant_id
        required: true
        schema:
          type: string
    get:
      tags: [Messages]
      summary: List messages
      responses:
        '200':
          description: A list of messages for the grant.
    post:
      tags: [Messages]
      summary: Send a message
      responses:
        '200':
          description: The sent message.
  /v3/grants/{grant_id}/threads:
    parameters:
      - in: path
        name: grant_id
        required: true
        schema:
          type: string
    get:
      tags: [Threads]
      summary: List threads
      responses:
        '200':
          description: A list of threads.
  /v3/grants/{grant_id}/drafts:
    parameters:
      - in: path
        name: grant_id
        required: true
        schema:
          type: string
    get:
      tags: [Drafts]
      summary: List drafts
      responses:
        '200':
          description: A list of drafts.
    post:
      tags: [Drafts]
      summary: Create a draft
      responses:
        '200':
          description: The created draft.
  /v3/grants/{grant_id}/calendars:
    parameters:
      - in: path
        name: grant_id
        required: true
        schema:
          type: string
    get:
      tags: [Calendars]
      summary: List calendars
      responses:
        '200':
          description: A list of calendars.
  /v3/grants/{grant_id}/events:
    parameters:
      - in: path
        name: grant_id
        required: true
        schema:
          type: string
    get:
      tags: [Events]
      summary: List events
      responses:
        '200':
          description: A list of calendar events.
    post:
      tags: [Events]
      summary: Create an event
      responses:
        '200':
          description: The created event.
  /v3/grants/{grant_id}/contacts:
    parameters:
      - in: path
        name: grant_id
        required: true
        schema:
          type: string
    get:
      tags: [Contacts]
      summary: List contacts
      responses:
        '200':
          description: A list of contacts.
  /v3/scheduling/configurations:
    get:
      tags: [Scheduling]
      summary: List scheduling configurations
      responses:
        '200':
          description: A list of scheduler configurations.
  /v3/scheduling/bookings:
    get:
      tags: [Scheduling]
      summary: List scheduler bookings
      responses:
        '200':
          description: A list of bookings.
  /v3/scheduling/availability:
    post:
      tags: [Scheduling]
      summary: Query availability
      responses:
        '200':
          description: Available slots for the requested participants.
  /v3/applications:
    get:
      tags: [Admin]
      summary: Retrieve application details
      responses:
        '200':
          description: Application record.
  /v3/connectors:
    get:
      tags: [Admin]
      summary: List provider connectors
      responses:
        '200':
          description: A list of connectors.
  /v3/webhooks:
    get:
      tags: [Admin]
      summary: List webhooks
      responses:
        '200':
          description: A list of webhook subscriptions.
    post:
      tags: [Admin]
      summary: Create a webhook
      responses:
        '200':
          description: The created webhook.
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Server-side requests use an API key issued in the Nylas dashboard
        and presented as a Bearer token. User-level requests use an
        access token obtained via the OAuth 2.0 flow.