Keap Email Address API

openapi: 3.2.0
info:
  title: Keap Email Address API
  contact:
    name: Keap
    url: https://developer.keap.com/get-support
    email: api.keap@thryv.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://www.thryv.com/terms-of-use
  version: '1.0'
  description: 'Operations tagged Email Address across 2 of this provider''s published API definitions: keap-v1-openapi.json, keap-v2-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.infusionsoft.com/crm
security:
- oauth2: []
tags:
- name: Email Address
  description: Email-Addresses-Endpoint
paths:
  /rest/v1/emailAddresses/{email}:
    put:
      tags:
      - Email Address
      summary: Replace an Email Address
      description: 'Replaces all of the values of a given email address


        You may opt-in or mark an email address as _Marketable_ by including the following field in the request JSON with an opt-in reason. (This field is also shown in the complete request body sample.) The reason you provide here will help with compliance. Example reasons: "Customer opted-in through webform", "Company gave explicit permission."


        ```json

        "opt_in_reason": "your reason for opt-in"

        ```

        Note that the email address status will only be updated to unconfirmed (marketable) for email addresses that are currently in the following states:

        Unengaged Marketable

        Unengaged Non-Marketable

        Non-Marketable

        Opt-Out: Manual

        All other existing statuses e.g. List Unsubscribe, Opt-Out System etc will remain non-marketable and in their existing state.'
      operationId: replaceEmailAddress
      parameters:
      - name: email
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailAddress'
        required: true
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '406':
          description: Not Acceptable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '412':
          description: Precondition Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelAndView'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestEmailAddress'
    servers:
    - url: https://api.infusionsoft.com/crm
  /rest/v2/emailAddresses/{email}/status:
    get:
      tags:
      - Email Address
      summary: Retrieve an Email Address status
      description: Retrieves the opt-in status for a given Email Address
      operationId: getEmailAddressStatus
      parameters:
      - name: email
        in: path
        required: true
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Method Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestEmailAddressStatus'
    patch:
      tags:
      - Email Address
      summary: Update an Email Address opt-in status
      description: 'Updates an Email Address opt-in status


        You may opt-in or mark an email address as _Marketable_ by including the following field in the request JSON

        with an opt-in reason. (This field is also shown in the complete request body sample.)

        The reason you provide here will help with compliance.

        Example reasons: "Customer opted-in through webform", "Company gave explicit permission."


        ```json

        "opt_in_reason": "your reason for opt-in"

        ```

        Note that the email address status will only be updated to `Unconfirmed` (marketable) for email addresses

        that are currently in the following states:

        - `Unengaged Marketable`

        - `Unengaged Non-Marketable`

        - `Non-Marketable`

        - `Opt-Out: Manual`


        All other existing statuses e.g. `List Unsubscribe`, `Opt-Out`, `System` etc will remain non-marketable and in their existing state.'
      operationId: updateEmailAddressOptStatus
      parameters:
      - name: email
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailAddress_2'
        required: true
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Method Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestEmailAddressStatus'
    servers:
    - url: https://api.infusionsoft.com/crm
  /rest/v2/emailAddresses:
    get:
      tags:
      - Email Address
      summary: List Email Address Statuses
      description: Retrieve a list of the Status of Email Addresses
      operationId: listEmailAddressStatuses
      parameters:
      - name: filter
        in: query
        description: 'Filter to apply, allowed fields are:

          - (Set[String]) `emails`

          - (Set[EmailOptStatus]) `statuses`

          - (Boolean) `opted_in`


          You will need to apply the `==` operator to check the equality of one of the filters with your searched

          word, in the encoded form `%3D%3D`.

          For the filters listed above, here are some examples:

          - `filter=opted_in%3D%3Dtrue`

          - `filter=emails%3D%3Dexample%40test.com`

          - `filter=emails%3D%3Dexample%40test.com%2Csecond%40test.com`

          '
        required: false
        schema:
          type: string
        example: filter=opted_in%3D%3Dtrue
      - name: page_token
        in: query
        description: Page token
        required: false
        schema:
          type: string
      - name: order_by
        in: query
        description: 'Attribute and direction to order items.

          One of the following fields:

          - `email`

          - `status`

          - `create_time`

          - `last_click_time`

          - `last_open_time`

          - `last_sent_time`


          One of the following directions:

          - `asc`

          - `desc`'
        required: false
        schema:
          type: string
        example: order_by=last_sent_time desc
      - name: page_size
        in: query
        description: Total number of items to return per page
        required: false
        schema:
          type: integer
          format: int32
          maximum: 1000
          minimum: 0
        example: 0
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Method Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmailAddressStatusResponse'
    servers:
    - url: https://api.infusionsoft.com/crm
components:
  schemas:
    DefaultHttpStatusCode:
      allOf:
      - $ref: '#/components/schemas/HttpStatusCode'
    UpdateEmailAddress:
      type: object
      properties:
        reason:
          type: string
        opted_in:
          type: boolean
      required:
      - opted_in
      - reason
    View:
      type: object
      properties:
        contentType:
          type: string
    ModelAndView:
      type: object
      properties:
        view:
          $ref: '#/components/schemas/View'
        model:
          type: object
          additionalProperties: {}
        status:
          oneOf:
          - $ref: '#/components/schemas/DefaultHttpStatusCode'
          - $ref: '#/components/schemas/HttpStatus'
        modelMap:
          type: object
          additionalProperties: {}
          properties:
            empty:
              type: boolean
        reference:
          type: boolean
        empty:
          type: boolean
        viewName:
          type: string
    RestEmailAddress:
      type: object
      properties:
        email:
          type: string
        opted_in:
          type: boolean
        status:
          type: string
          enum:
          - Unengaged Marketable
          - Unconfirmed
          - Confirmed (Legacy)
          - Confirmed
          - Unengaged NonMarketable
          - Non-marketable
          - Lockdown
          - Soft Bounce
          - Hard Bounce
          - Opt-Out
          - 'Opt-Out: Admin'
          - 'Opt-Out: System'
          - List Unsubscribe
          - Provided Feedback
          - Reported Spam
          - Invalid Email
          - Deactivated/Delinquent Mailbox
      required:
      - email
      - opted_in
      - status
    HttpStatus:
      allOf:
      - $ref: '#/components/schemas/HttpStatusCode'
      enum:
      - 100 CONTINUE
      - 101 SWITCHING_PROTOCOLS
      - 102 PROCESSING
      - 103 EARLY_HINTS
      - 200 OK
      - 201 CREATED
      - 202 ACCEPTED
      - 203 NON_AUTHORITATIVE_INFORMATION
      - 204 NO_CONTENT
      - 205 RESET_CONTENT
      - 206 PARTIAL_CONTENT
      - 207 MULTI_STATUS
      - 208 ALREADY_REPORTED
      - 226 IM_USED
      - 300 MULTIPLE_CHOICES
      - 301 MOVED_PERMANENTLY
      - 302 FOUND
      - 303 SEE_OTHER
      - 304 NOT_MODIFIED
      - 307 TEMPORARY_REDIRECT
      - 308 PERMANENT_REDIRECT
      - 400 BAD_REQUEST
      - 401 UNAUTHORIZED
      - 402 PAYMENT_REQUIRED
      - 403 FORBIDDEN
      - 404 NOT_FOUND
      - 405 METHOD_NOT_ALLOWED
      - 406 NOT_ACCEPTABLE
      - 407 PROXY_AUTHENTICATION_REQUIRED
      - 408 REQUEST_TIMEOUT
      - 409 CONFLICT
      - 410 GONE
      - 411 LENGTH_REQUIRED
      - 412 PRECONDITION_FAILED
      - 413 CONTENT_TOO_LARGE
      - 413 PAYLOAD_TOO_LARGE
      - 414 URI_TOO_LONG
      - 415 UNSUPPORTED_MEDIA_TYPE
      - 416 REQUESTED_RANGE_NOT_SATISFIABLE
      - 417 EXPECTATION_FAILED
      - 418 I_AM_A_TEAPOT
      - 421 MISDIRECTED_REQUEST
      - 422 UNPROCESSABLE_CONTENT
      - 422 UNPROCESSABLE_ENTITY
      - 423 LOCKED
      - 424 FAILED_DEPENDENCY
      - 425 TOO_EARLY
      - 426 UPGRADE_REQUIRED
      - 428 PRECONDITION_REQUIRED
      - 429 TOO_MANY_REQUESTS
      - 431 REQUEST_HEADER_FIELDS_TOO_LARGE
      - 451 UNAVAILABLE_FOR_LEGAL_REASONS
      - 500 INTERNAL_SERVER_ERROR
      - 501 NOT_IMPLEMENTED
      - 502 BAD_GATEWAY
      - 503 SERVICE_UNAVAILABLE
      - 504 GATEWAY_TIMEOUT
      - 505 HTTP_VERSION_NOT_SUPPORTED
      - 506 VARIANT_ALSO_NEGOTIATES
      - 507 INSUFFICIENT_STORAGE
      - 508 LOOP_DETECTED
      - 509 BANDWIDTH_LIMIT_EXCEEDED
      - 510 NOT_EXTENDED
      - 511 NETWORK_AUTHENTICATION_REQUIRED
    HttpStatusCode:
      type: object
      properties:
        error:
          type: boolean
        is1xxInformational:
          type: boolean
        is2xxSuccessful:
          type: boolean
        is3xxRedirection:
          type: boolean
        is4xxClientError:
          type: boolean
        is5xxServerError:
          type: boolean
    UpdateEmailAddress_2:
      type: object
      description: Request to update email address opt-in status
      properties:
        reason:
          type: string
          description: Reason for the opt-in status change
          example: Customer requested to receive marketing emails
        opted_in:
          type: boolean
          description: Whether to opt-in the email address
          example: true
      required:
      - opted_in
      - reason
    ErrorDetails:
      type: object
      properties:
        domain:
          type: string
        resource:
          type: string
    RestEmailAddressStatus:
      type: object
      description: Email address opt-in status information
      properties:
        email:
          type: string
          description: The email address
          example: john@example.com
        opted_in:
          type: boolean
          description: Whether the email address is opted in for marketing
          example: true
        status:
          type: string
          description: The opt-in status of the email address
          enum:
          - UNENGAGED_MARKETABLE
          - SINGLE_OPT_IN
          - DOUBLE_OPT_IN
          - CONFIRMED
          - UNENGAGED_NON_MARKETABLE
          - NON_MARKETABLE
          - LOCKDOWN
          - BOUNCE
          - HARD_BOUNCE
          - MANUAL
          - ADMIN
          - SYSTEM
          - LIST_UNSUBSCRIBE
          - FEEDBACK
          - SPAM
          - INVALID
          - DEACTIVATED
          example: SINGLE_OPT_IN
        create_time:
          type: string
          format: date-time
          description: When the email status was first recorded, in ISO-8601 format
          example: '2024-05-21T14:30:00Z'
        last_click_time:
          type: string
          format: date-time
          description: The most recent click on an email sent to this address, in ISO-8601 format
          example: '2024-05-21T15:05:00Z'
        last_open_time:
          type: string
          format: date-time
          description: The most recent open of an email sent to this address, in ISO-8601 format
          example: '2024-05-21T15:00:00Z'
        last_sent_time:
          type: string
          format: date-time
          description: The most recent time an email was sent to this address, in ISO-8601 format
          example: '2024-05-21T14:30:00Z'
      required:
      - create_time
      - email
      - opted_in
      - status
    ListEmailAddressStatusResponse:
      type: object
      properties:
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/RestEmailAddressStatus'
        next_page_token:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        status:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.infusionsoft.com/app/oauth/authorize
          tokenUrl: https://api.infusionsoft.com/token
          scopes: {}
x-refined-from:
- keap-v1-openapi.json
- keap-v2-openapi.json