> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecorn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Report a wrong email address

> Flag an email Pipecorn returned as wrong and search for another one

Use this endpoint when one of your users finds that an email address Pipecorn
enriched is wrong: it bounces, it is at the wrong company, or it belongs to
someone else. Pipecorn removes the address from the contact and, by default,
searches for another one of the same type, work or personal, with the
providers that did not give the wrong address.

## Flow

1. Send the contact's `linkedin_url`, the wrong `email` and a `reason`.
2. The response says whether a new search started (`replacement: "searching"`).
3. Poll `status_url` until `status` is `finished`, or wait for the webhook. It
   carries the new address in `email` (or `personal_email`), or no address
   when none was found.

```bash theme={null}
curl -X POST https://app.pipecorn.com/api/v2/contacts/report_email \
  -H "X-API-Key: $PIPECORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_url": "https://www.linkedin.com/in/william-hewish",
    "email": "william.hewish@acme.com",
    "reason": "wrong_domain",
    "webhook_url": "https://example.com/pipecorn/emails"
  }'
```

## Credits

Reporting is free. The new search costs what an enrichment of the same type
costs, and only when it finds an address: 3 credits for a work email, 9 for a
personal email. A personal email search also needs the account's consent to
personal email enrichment. Send `"find_replacement": false` to report the
address without searching.


## OpenAPI

````yaml api-reference/specs/enrichments.json POST /contacts/report_email
openapi: 3.0.1
info:
  title: Pipecorn Enrichments API
  description: Pipecorn List API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.pipecorn.com/api/v2/
security:
  - defaultApiKey: []
paths:
  /contacts/report_email:
    post:
      summary: Report a wrong email address
      description: >-
        Tell Pipecorn that an email address it returned for a contact is wrong,
        and search for another one.


        The address is removed from the contact: [`GET
        /contacts/{id}`](/api-reference/endpoints/contacts/single_enrich), the
        enrichment webhook and later enrichments of the same person no longer
        return it. Unless `find_replacement` is `false`, a new search of the
        same type starts at once: a work email starts a work email search, a
        personal email a personal email search. It skips the providers that gave
        the wrong address, and runs only when no other verified email of the
        same type is left on the contact.


        **Credits:** reporting is free. The new search costs what an enrichment
        of the same type costs, and only when an address is found: 3 credits for
        a work email, 9 for a personal email. A personal email search also needs
        account-level GDPR consent, like `personal_email` in [single
        enrichment](/api-reference/endpoints/enrichments/single).


        **Result:** the response comes back right away. While the search runs,
        `GET /contacts/{id}` answers `status: "pending"`. When it ends, the
        `webhook_url` (or the one sent with the original enrichment) receives
        the same payload as [single
        enrichment](/api-reference/endpoints/enrichments/single#receiving-results),
        with the new address in `email` (or `personal_email`) or none.


        The report always lands when the contact and address are found: a plan
        without email enrichment, a personal email without the consent, or a
        balance below the price of the search still removes the address and says
        in `replacement` why no search ran. Reporting the same address again
        while its search runs does not start a second one.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - linkedin_url
                - email
                - reason
              properties:
                linkedin_url:
                  type: string
                  description: >-
                    LinkedIn profile URL of the contact, as sent to the
                    enrichment.
                  example: https://www.linkedin.com/in/william-hewish
                email:
                  type: string
                  format: email
                  description: >-
                    The wrong address, as Pipecorn returned it: a work email or
                    a personal email. Use the full address.
                  example: william.hewish@acme.com
                reason:
                  type: string
                  enum:
                    - invalid_address
                    - wrong_domain
                    - wrong_person
                  description: >-
                    `invalid_address`: the address bounces or does not exist.
                    `wrong_domain`: the address is at a company the person no
                    longer works for, or at the wrong company. `wrong_person`:
                    the address belongs to someone else.
                find_replacement:
                  type: boolean
                  default: true
                  description: >-
                    Search for another address. Send `false` to only report the
                    address.
                webhook_url:
                  type: string
                  format: uri
                  description: >-
                    Where to send the result of the new search. Defaults to the
                    `webhook_url` of the original enrichment.
      responses:
        '200':
          description: The address is reported
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrichment_id:
                    type: string
                    format: uuid
                    description: The contact's enrichment ID, for `GET /contacts/{id}`
                  reported:
                    type: boolean
                    description: Always `true`
                  replacement:
                    type: string
                    enum:
                      - searching
                      - other_email_kept
                      - not_allowed
                      - insufficient_credits
                      - skipped
                    description: >-
                      `searching`: a new email search of the same type is
                      running. `other_email_kept`: the contact still has another
                      verified email of the same type, so no search ran.
                      `not_allowed`: your plan or role does not allow this email
                      enrichment, or the account has not consented to personal
                      email enrichment. `insufficient_credits`: fewer credits
                      left than the search costs (3 for a work email, 9 for a
                      personal email). `skipped`: you sent `find_replacement:
                      false`.
                  status_url:
                    type: string
                    format: uri
                    description: '`GET /contacts/{id}` for this contact'
              example:
                enrichment_id: 8f1c2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b
                reported: true
                replacement: searching
                status_url: >-
                  https://app.pipecorn.com/api/v2/contacts/8f1c2a4e-5b6d-4e7f-9a0b-1c2d3e4f5a6b
        '400':
          description: '`linkedin_url`, `email` or `reason` is missing'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Missing required keys: reason'
        '404':
          description: >-
            No contact with this LinkedIn URL is reachable with your key, or the
            address is not on it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Email not found on this contact
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          description: >-
            `linkedin_url` is not a public profile URL, `email` is not a full
            address, `reason` is not `invalid_address`, `wrong_domain` or
            `wrong_person`, `find_replacement` is not a boolean, or
            `webhook_url` is not an http(s) URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid email, use a full address (e.g. jane@acme.com)
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        A unique value you generate per operation, such as a UUID. Retrying with
        the same key and the same body returns the stored response instead of
        running the request again, so a retry after a timeout never charges
        twice. Successful responses are kept for 24 hours; a failed request is
        not stored and can be retried with the same key.
      schema:
        type: string
        maxLength: 255
        example: 4f1c2e9a-8a7d-4c1b-9f63-2d6e0b5a7c11
  schemas:
    Error:
      required:
        - error
      type: object
      properties:
        error:
          description: >-
            Human-readable error message. A few validation errors return a list
            of messages instead of a single string.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        message:
          type: string
          description: >-
            Longer explanation, sent by validators that add context. Such errors
            may also carry extra top-level keys like `valid_values` or
            `example`.
        details:
          type: string
          description: >-
            Parser message, sent with `"Invalid JSON format in request body"`
            when the request body is not valid JSON.
  responses:
    IdempotencyConflict:
      description: >-
        A request with this `Idempotency-Key` is still being processed. Wait for
        the `Retry-After` delay and retry with the same key.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              code:
                type: string
                enum:
                  - idempotency_key_in_use
          example:
            error: A request with this Idempotency-Key is still being processed
            code: idempotency_key_in_use
  headers:
    Retry-After:
      description: >-
        Seconds to wait before retrying. Sent when the plan limit or a request
        still in progress caused the error.
      schema:
        type: integer
        example: 42
  securitySchemes:
    defaultApiKey:
      type: apiKey
      in: header
      description: Your API key
      name: X-API-KEY

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.