Generect 7. Email API

openapi: 3.2.0
info:
  title: Generect 7. Email API
  description: 'Welcome to the Generect API documentation. Here we will help you integrate and use our API.


    API base url: `https://api.generect.com` — every path below is relative to this host. Newer endpoints live under `/api/v1/...`, legacy endpoints under `/api/...`; use each path exactly as documented.

    Protocol: `HTTPS`


    # Authentication


    Get your API token from the Generect app settings and send it in the `Authorization` header with the required `Token` prefix.


    Example: `Authorization: Token xxxxxxxxx`


    # Rate limits


    There is no monthly request quota. What you can run is bounded by your account balance and by the parallel-request caps on the Limits page. Pricing depends on the operation and the number of results returned, and may increase with additional data flags. For exact pricing, see each endpoint''s Pricing section or your billing settings: https://app.generect.com/settings/billing


    # Note


    _Every endpoint must include the trailing `/`. Requests without the trailing slash may fail._'
  version: 1.0.0
  contact: {}
servers:
- url: https://api.generect.com
security:
- apiKey: []
tags:
- name: 7. Email
  description: Find and validate email addresses.
paths:
  /api/v1/email/find/:
    post:
      tags:
      - 7. Email
      summary: Find email
      description: Find a verified work email by lead ID, LinkedIn URL, or by name and domain. Billed only when a valid email is found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - title: By Lead ID
                type: object
                required:
                - lead_id
                properties:
                  lead_id:
                    type: string
                    description: Generect lead identifier from Search, Preview, or Enrich.
                    example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
              - title: By LinkedIn URL
                type: object
                required:
                - linkedin_url
                properties:
                  linkedin_url:
                    type: string
                    description: Lead's LinkedIn profile URL.
                    example: https://www.linkedin.com/in/jordan-ellis
              - title: By Name and Domain
                type: object
                required:
                - first_name
                - last_name
                - domain
                properties:
                  first_name:
                    type: string
                    description: Lead's first name.
                    example: John
                  last_name:
                    type: string
                    description: Lead's last name.
                    example: Doe
                  middle_name:
                    type: string
                    description: Lead's middle name. Optional; used to widen the pattern set when the company uses middle names.
                    example: A.
                  domain:
                    type: string
                    description: Company domain used to generate the email pattern.
                    example: microsoft.com
            examples:
              By Lead ID:
                value:
                  lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
              By LinkedIn URL:
                value:
                  linkedin_url: https://www.linkedin.com/in/jordan-ellis
              By name and domain:
                value:
                  first_name: Jordan
                  last_name: Ellis
                  domain: microsoft.com
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail:
                      non_field_errors:
                      - 'Provide one of: lead_id, linkedin_url, or first_name+last_name+domain.'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Email result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailFindResponse'
              examples:
                Found:
                  value:
                    data:
                      valid_email: jordan.ellis@microsoft.com
                      result: valid
                      catch_all: false
                      source: generect
                    meta:
                      amount_charged: 0.02
                Not found:
                  value:
                    data:
                      valid_email: null
                    meta:
                      amount_charged: 0
      operationId: postApiV1EmailFind
      x-operation-id-source: derived
  /api/v1/email/find/bulk/:
    post:
      tags:
      - 7. Email
      summary: Start bulk email find
      description: Start an asynchronous bulk email find job. Billed only for valid emails found.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - leads
              properties:
                leads:
                  type: array
                  maxItems: 50
                  description: 'Leads to find emails for (max 50 per request). Each entry is one of: {lead_id}, {linkedin_url}, or {first_name, last_name, domain}.'
                  items:
                    oneOf:
                    - title: By Lead ID
                      type: object
                      required:
                      - lead_id
                      properties:
                        lead_id:
                          type: string
                          example: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                    - title: By LinkedIn URL
                      type: object
                      required:
                      - linkedin_url
                      properties:
                        linkedin_url:
                          type: string
                          example: https://www.linkedin.com/in/jordan-ellis
                    - title: By Name and Domain
                      type: object
                      required:
                      - first_name
                      - last_name
                      - domain
                      properties:
                        first_name:
                          type: string
                          description: Lead's first name.
                        middle_name:
                          type: string
                          description: Lead's middle name. Optional.
                        last_name:
                          type: string
                          description: Lead's last name.
                        domain:
                          type: string
                          description: Company domain.
            examples:
              Bulk email find:
                value:
                  leads:
                  - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                  - first_name: Morgan
                    last_name: Lee
                    domain: salesforce.com
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail:
                      leads:
                      - This field is required.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '202':
          description: Bulk job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSubmitResponse'
              example:
                data: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: pending
                  total: 2
                  processed: 0
                  amount_charged: 0
                  error: null
      operationId: postApiV1EmailFindBulk
      x-operation-id-source: derived
  /api/v1/email/find/bulk/{job_id}/:
    get:
      tags:
      - 7. Email
      summary: Get bulk email find job
      description: Retrieve the status and results of a bulk email find job.
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
        example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
      responses:
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Job not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
              example:
                detail: Job not found
        '200':
          description: Bulk job status and results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkStatusResponse'
              example:
                data:
                - lead_id: ACwAAAE9bk0BxY7Qf2mN4pR8sT1vW3zA5cE6gH9
                  valid_email: jordan.ellis@microsoft.com
                  result: valid
                  catch_all: false
                  source: generect
                - valid_email: null
                meta:
                  job_id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                  status: completed
                  total: 2
                  processed: 2
                  amount_charged: 0.02
                  error: null
      operationId: getApiV1EmailFindBulkByJobId
      x-operation-id-source: derived
  /api/v1/email/validate/:
    post:
      tags:
      - 7. Email
      summary: Validate emails
      description: Validate email deliverability and risk. Billed per email validated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
              example:
                emails:
                - jordan.ellis@microsoft.com
                - morgan.lee@salesforce.com
      responses:
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                Validation error:
                  value:
                    status: error
                    status_code: 400
                    detail:
                      emails:
                      - This field is required.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '200':
          description: Validation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidateResponse'
              example:
                data:
                - email: jordan.ellis@microsoft.com
                  result: valid
                  exist: 'yes'
                  catch_all: false
                  error: null
                - email: morgan.lee@salesforce.com
                  result: valid
                  exist: 'yes'
                  catch_all: false
                  error: null
                meta:
                  amount_charged: 0.01
      operationId: postApiV1EmailValidate
      x-operation-id-source: derived
components:
  responses:
    Forbidden:
      description: Authenticated, but the account/plan is not allowed to use this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 403
            detail: You do not have permission to perform this action.
    PaymentRequired:
      description: Not enough balance to run a billable request. Top up in your billing settings; requests already accepted run to completion.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 402
            detail: Insufficient funds in the account.
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: error
            status_code: 401
            detail: Authentication credentials were not provided.
  schemas:
    BulkStatusResponse:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          description: Result items once status is completed; null until then.
          items:
            type: object
        meta:
          $ref: '#/components/schemas/BulkJobMeta'
    EmailFindResponse:
      type: object
      properties:
        data:
          type: object
          description: The email finder result. valid_email is null when no email is found.
          properties:
            lead_id:
              type: string
              description: Echoed back when the request was made by lead_id.
            valid_email:
              type:
              - string
              - 'null'
              description: The found verified email, or null if none was found.
            result:
              type: string
              description: 'Outcome: valid, invalid, or unknown.'
            catch_all:
              type: boolean
              description: True if the domain is catch-all.
            source:
              type: string
              description: Where the email was resolved (e.g. generect, findymail, FORMAT).
            email_format:
              type: string
              description: Detected address pattern for the domain.
            mx_domain:
              type: string
              description: Mail exchanger domain.
        meta:
          $ref: '#/components/schemas/Meta'
    Error:
      type: object
      description: Standard error envelope returned for 4xx/5xx responses.
      properties:
        status:
          type: string
          example: error
        status_code:
          type: integer
          example: 400
        detail:
          description: 'Human-readable message (string) for most errors, or a field-level validation map ({ field: [messages] }) for 400 validation errors.'
          example: Person does not exist
    BulkSubmitResponse:
      type: object
      properties:
        data:
          type:
          - object
          - 'null'
          description: Always null — results arrive via the bulk status endpoint.
        meta:
          $ref: '#/components/schemas/BulkJobMeta'
    EmailValidateResponse:
      type: object
      properties:
        data:
          type: array
          description: One validation result per submitted email, in input order.
          items:
            type: object
            properties:
              email:
                type: string
                description: The validated email address.
              result:
                type: string
                description: 'Validation outcome: valid, invalid, catch_all, or unknown.'
              exist:
                type: string
                description: Whether the mailbox exists (e.g. "yes", "no").
              catch_all:
                type: boolean
                description: True if the domain accepts mail for any address (catch-all).
              error:
                type:
                - string
                - 'null'
                description: Reason the address could not be validated; null on success.
        meta:
          $ref: '#/components/schemas/Meta'
    Meta:
      type: object
      description: Operation metadata returned in every data/meta response.
      required:
      - amount_charged
      properties:
        amount_charged:
          type: number
          description: Actual amount charged for this request in USD, computed from your pricing tier. 0 for free operations and for not-found results (No Data — No Charge).
        status:
          type: string
          description: Set to "error" when the operation finished with an error.
        error:
          type: string
          description: Error details; present only when the operation failed.
        time_cached:
          type: string
          format: date-time
          description: When the cached result set was originally collected (returned by database company search when results are served from a previous identical search).
        free_tier:
          type: object
          description: 'Present only on a database lead or company search sent with `"detail": "thin"`: where your account stands against today''s free row quota. The quota resets at 00:00 UTC.'
          properties:
            detail:
              type: string
              enum:
              - thin
            daily_rows:
              type: integer
              description: Free thin rows per account per UTC day.
            rows_used_today:
              type: integer
              description: Thin rows returned to your account today, this page included.
            rows_left_today:
              type: integer
              description: Thin rows your account can still take today.
    BulkJobMeta:
      type: object
      description: Bulk job state. Poll the bulk status endpoint with job_id or subscribe to the completion webhook.
      required:
      - job_id
      - status
      - total
      - processed
      - amount_charged
      properties:
        job_id:
          type: string
          description: Job identifier — pass it to the bulk status endpoint.
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - error
        total:
          type: integer
          description: Number of submitted items.
        processed:
          type: integer
          description: Items processed so far.
        found:
          type: integer
          description: Items that resolved to a result (present on status/webhook once completed).
        not_found:
          type: integer
          description: Items with no result — not charged (No Data, No Charge).
        amount_charged:
          type: number
          description: USD charged for found results; final when status is completed.
        error:
          type:
          - string
          - 'null'
          description: Failure reason when status is error.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use the required Token prefix. Example: Authorization: Token xxxxxxxxx'