Nylas Signatures API

openapi: 3.2.0
info:
  title: Nylas Signatures API
  version: v3
  summary: The complete Nylas v3 API — Email, Calendar, Contacts, Notetaker, Scheduling, Administration, and Migration.
  description: The Nylas API is designed using the REST ideology to provide simple and predictable URIs to access and modify objects. Requests support standard HTTP methods like `GET`, `PUT`, `POST`, and `DELETE`, and standard status codes. Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise. You can use the Nylas Postman collection to quickly start using the Nylas APIs. For more information, check out the Nylas Postman collection documentation.
  contact:
    url: https://www.nylas.com/
servers:
- url: https://api.us.nylas.com
  description: U.S.
- url: https://api.eu.nylas.com
  description: E.U.
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
tags:
- name: Signatures
  description: 'The Nylas Signatures API lets you create and store HTML email signatures on Nylas, and reference them by ID when sending messages or creating drafts. Nylas appends the signature to the end of the email body at send time.


    Nylas signatures are managed entirely through this API and are separate from any signatures configured in the user''s email provider (Gmail, Outlook, etc.). Provider signatures are not synced to Nylas, and are not applied to emails sent through the Nylas API.


    Each grant supports up to 10 signatures, so users can maintain variants for different contexts (for example, "Work", "Personal", or "Mobile"). Signatures are automatically deleted when the parent grant is deleted.


    For more information, see the Using email signatures documentation.'
paths:
  /v3/grants/{grant_id}/signatures:
    parameters:
    - schema:
        type: string
      name: grant_id
      in: path
      required: true
      description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
    get:
      summary: Return all signatures
      tags:
      - Signatures
      x-scopes: {}
      responses:
        '200':
          $ref: '#/components/responses/signatures'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
        '504':
          $ref: '#/components/responses/504'
      operationId: list-signatures
      description: Return all signatures for a grant.
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page_token'
      - $ref: '#/components/parameters/field_selection'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request GET \\\n  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
    post:
      summary: Create a signature
      operationId: post-signature
      description: 'Create a signature for a grant. Each grant can have up to 10 signatures.


        Nylas sanitizes the HTML content on input to prevent malicious content. Images must use

        externally hosted URLs (base64 inline images are not supported). Maximum signature size is 100 KB.'
      tags:
      - Signatures
      x-scopes: {}
      requestBody:
        $ref: '#/components/requestBodies/signature_create'
      responses:
        '201':
          $ref: '#/components/responses/signature'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
        '504':
          $ref: '#/components/responses/504'
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
      parameters:
      - $ref: '#/components/parameters/field_selection'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request POST \\\n  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n  --data '{\n    \"name\": \"Work Signature\",\n    \"body\": \"<div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p><p><a href=\\\"mailto:nick@nylas.com\\\">nick@nylas.com</a></p></div>\"\n  }'\n"
  /v3/grants/{grant_id}/signatures/{signature_id}:
    parameters:
    - schema:
        type: string
      name: grant_id
      in: path
      required: true
      description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token.
    - schema:
        type: string
      name: signature_id
      in: path
      required: true
      description: ID of the signature to access.
    get:
      summary: Return a signature
      tags:
      - Signatures
      x-scopes: {}
      responses:
        '200':
          $ref: '#/components/responses/signature'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '504':
          $ref: '#/components/responses/504'
      operationId: get-signature
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
      description: Return a signature by ID.
      parameters:
      - $ref: '#/components/parameters/field_selection'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request GET \\\n  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
    put:
      summary: Update a signature
      tags:
      - Signatures
      x-scopes: {}
      responses:
        '200':
          $ref: '#/components/responses/signature'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '504':
          $ref: '#/components/responses/504'
      operationId: put-signature
      description: 'Update the specified signature. You can update the `name`, `body`, or both. The signature ID

        does not change.'
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
      parameters:
      - $ref: '#/components/parameters/field_selection'
      requestBody:
        $ref: '#/components/requestBodies/signature_update'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request PUT \\\n  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \\\n  --header 'Content-Type: application/json' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n  --data '{\n    \"name\": \"Updated Work Signature\",\n    \"body\": \"<div><p><strong>Nick Barraclough</strong></p><p>Senior Product Manager | Nylas</p><p><a href=\\\"mailto:nick@nylas.com\\\">nick@nylas.com</a></p></div>\"\n  }'\n"
    delete:
      summary: Delete a signature
      tags:
      - Signatures
      x-scopes: {}
      responses:
        '200':
          $ref: '#/components/responses/200-delete'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '504':
          $ref: '#/components/responses/504'
      operationId: delete-signature
      description: 'Permanently delete a signature. Signatures are also automatically deleted when the parent grant

        is deleted.'
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --request DELETE \\\n  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/signatures/<SIGNATURE_ID>' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>'\n"
components:
  schemas:
    signature:
      title: Signature
      type: object
      properties:
        id:
          type: string
          description: Globally unique identifier for the signature.
          readOnly: true
          example: sig_abc123
        grant_id:
          $ref: '#/components/schemas/grant_id'
        name:
          type: string
          description: A label for the signature (for example, "Work", "Personal", or "Mobile").
          example: Work Signature
        body:
          type: string
          description: The HTML content of the signature. Images must use externally hosted URLs.
          example: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p></div>
        object:
          type: string
          description: The type of object.
          example: signature
          readOnly: true
        created_at:
          type: integer
          description: Unix timestamp when the signature was created.
          readOnly: true
          example: 1706367600
        updated_at:
          type: integer
          description: Unix timestamp when the signature was last modified.
          readOnly: true
          example: 1706367600
    grant_id:
      title: Grant ID
      type: string
      description: The ID of grant for the connected user.
      example: 41009df5-bf11-4c97-aa18-b285b5f2e386
      readOnly: true
    common_response:
      properties:
        request_id:
          type: string
          description: The request ID.
        data:
          type: object
          description: The response object.
      example:
        request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
    common_response_with_cursor:
      properties:
        request_id:
          type: string
          description: The request ID.
        data:
          type: array
          description: The list of objects returned by the request.
          items:
            type: object
        next_cursor:
          type:
          - string
          - 'null'
          description: A cursor pointing to the next page of results for the request.
      example:
        request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
        next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
  responses:
    200-delete:
      description: Delete Succeeded
      content:
        application/json:
          schema:
            type: object
            required:
            - request_id
            properties:
              request_id:
                type: string
                description: ID of the request.
                example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
    signature:
      description: Signature
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/common_response'
            - properties:
                data:
                  $ref: '#/components/schemas/signature'
          example:
            request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
            data:
              id: sig_abc123
              grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
              name: Work Signature
              body: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p><p><a href="mailto:nick@nylas.com">nick@nylas.com</a></p></div>
              object: signature
              created_at: 1706367600
              updated_at: 1706367600
    '504':
      description: Provider Failure
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
          examples:
            Provider Failure:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: provider_error
                  message: Provider request timed out.
    '404':
      description: Not Found
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The raw error from the provider, if available
                    properties:
                      code:
                        type: string
                      message:
                        type: string
          examples:
            Not Found:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: not_found_error
                  message: requested object not found
                  provider_error:
                    code: MailboxNotEnabledForRESTAPI
                    message: The mailbox is either inactive, soft-deleted, or is hosted on-premise.
    '429':
      description: 'Rate limited. The provider or Nylas throttled the request. If a provider throttles a request and

        says how long to wait, the `Retry-After` header gives that number of seconds. When the header

        is missing, retry with exponential backoff. See

        [429 rate limit errors by provider](/docs/api/errors/400-response/#429-rate-limit-errors-by-provider).'
      headers:
        Retry-After:
          description: 'The number of seconds to wait before retrying, rounded up. Present only when the provider, or

            Nylas for an Agent Account send, said how long to wait.'
          schema:
            type: integer
            example: 30
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The provider's own error, when the provider returned one.
          examples:
            Rate limited:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: rate_limit_error
                  message: Too many requests. If you see this error when fetching objects, set your limit=20 or lower. See http://nyl.as/429-tmr.
    signatures:
      description: Signatures
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/common_response_with_cursor'
            - properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/signature'
          example:
            request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
            data:
            - id: sig_abc123
              grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
              name: Work Signature
              body: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p></div>
              object: signature
              created_at: 1706367600
              updated_at: 1706367600
            - id: sig_def456
              grant_id: 41009df5-bf11-4c97-aa18-b285b5f2e386
              name: Personal Signature
              body: <div><p>Nick B.</p><p>Sent from my phone</p></div>
              object: signature
              created_at: 1706367700
              updated_at: 1706367700
            next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The error from the provider.
          examples:
            Unauthorized:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: unauthorized
                  message: Unauthorized
                  provider_error:
                    code: 401
                    message: Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The error from the provider.
          examples:
            Bad Request:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: invalid_request_error
                  message: error parsing request body
                  provider_error:
                    code: TargetIdShouldNotBeMeOrWhitespace
                    message: Id is malformed.
            Invalid Idempotency-Key:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: api.invalid_idempotency_key
                  message: Idempotency-Key must be 256 characters or fewer.
  requestBodies:
    signature_update:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
                description: Updated label for the signature.
                example: Updated Work Signature
              body:
                type: string
                description: 'Updated HTML content for the signature. Maximum 100 KB. Images must use externally hosted

                  URLs (base64 inline images are not supported). Nylas sanitizes the HTML on input to prevent

                  malicious content.'
                example: <div><p><strong>Nick Barraclough</strong></p><p>Senior Product Manager | Nylas</p></div>
          example:
            name: Updated Work Signature
            body: <div><p><strong>Nick Barraclough</strong></p><p>Senior Product Manager | Nylas</p></div>
    signature_create:
      content:
        application/json:
          schema:
            type: object
            required:
            - name
            - body
            properties:
              name:
                type: string
                description: A label for the signature (for example, "Work", "Personal", or "Mobile").
                example: Work Signature
              body:
                type: string
                description: 'The HTML content of the signature. Maximum 100 KB. Images must use externally hosted URLs

                  (base64 inline images are not supported). Nylas sanitizes the HTML on input to prevent

                  malicious content.'
                example: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p><p><a href="mailto:nick@nylas.com">nick@nylas.com</a></p></div>
          example:
            name: Work Signature
            body: <div><p><strong>Nick Barraclough</strong></p><p>Product Manager | Nylas</p><p><a href="mailto:nick@nylas.com">nick@nylas.com</a></p></div>
  parameters:
    page_token:
      name: page_token
      in: query
      required: false
      schema:
        type: string
      description: 'An identifier that specifies which page of data to return. You can get this value from the

        `next_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more

        information.'
    field_selection:
      name: select
      in: query
      required: false
      schema:
        type: string
      description: 'Specify fields that you want Nylas to return, as a comma-separated list (for example,

        `select=id,updated_at`). This allows you to receive only the portion of object data that you''re

        interested in. You can use `select` to optimize response size and reduce latency by limiting queries

        to only the information that you need.'
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 50
        maximum: 200
      description: 'The maximum number of objects to return. See [Pagination](/docs/reference/api/#pagination)

        for more information.'
  securitySchemes:
    IAM_API_KEY:
      type: http
      scheme: bearer
      bearerFormat: IAM API key
      description: An active, unexpired IAM credential of type `api_key` whose principal is active, has an Organization resource binding, and has the required IAM management permission. Use an existing IAM credential with these permissions, or [create your first management credential in the Dashboard](/docs/v3/auth/nylas-iam/manage-principals-with-api/#create-a-management-credential-in-the-dashboard). Application API keys (including legacy API keys) and provider OAuth tokens cannot authorize IAM management endpoints.
    ACCESS_TOKEN:
      scheme: bearer
      type: http
      bearerFormat: NYLAS_ACCESS_TOKEN
      description: 'The Nylas **access token** for a specific grant. Issued as part of OAuth 2.1 flow token

        exchange.'
    NYLAS_API_KEY:
      scheme: bearer
      type: http
      bearerFormat: NYLAS_API_KEY
      description: 'The Nylas **API key** provides application-level access to APIs and all grants. You can

        generate these from the Dashboard. Learn more about [authorizing requests](/docs/v3/auth/).'
    SCHEDULER_SESSION_TOKEN:
      scheme: bearer
      type: http
      bearerFormat: Session ID
      description: The Nylas Scheduler **session ID** that Scheduler UI Components use to authorize API requests.
x-provenance:
  method: harvested
  publisher: Nylas
  source: https://developer.nylas.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)