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

# Get Contact by Email

> Retrieve a contact and all its data by email address

<Tip>
  Use this endpoint to look up a contact's ID, then use **[Update by
  ID](/api-reference/core-data/contacts/update-by-id)** to modify it — for example, to change the contact's email
  address.
</Tip>

## Use Cases

* **Look up contact ID**: Find a contact's internal ID to use with other endpoints
* **Check if contact exists**: Verify whether an email is already in your contact list
* **Read contact data**: Retrieve full contact details including custom fields

## Response

Returns the full contact object:

```json theme={null}
{
  "data": {
    "id": 42,
    "email": "customer@example.com",
    "phone": "+393391234567",
    "status": "active",
    "source": "API",
    "custom_fields": {
      "company": "Acme Corp",
      "plan": "enterprise"
    },
    "company": 1,
    "deleted": false,
    "external_id": null,
    "external_connection_id": null
  }
}
```

<Note>Soft-deleted contacts are not returned — a `404` is returned instead.</Note>

## Common Errors

| Error          | Cause                      | Solution                               |
| -------------- | -------------------------- | -------------------------------------- |
| `bad_request`  | Invalid email format       | Ensure the email address is valid      |
| `not_found`    | No contact with this email | Check the email address                |
| `unauthorized` | Invalid API key            | Verify API key in Authorization header |

## Example: Look Up and Update a Contact

```javascript theme={null}
const API_URL = 'https://api.minimo.it/public/v1/contacts';
const headers = {
  Authorization: 'Bearer mn-YOUR_CLIENT_ID-YOUR_API_KEY',
  'Content-Type': 'application/json',
};

// Step 1: Get the contact by email
const email = 'customer@example.com';
const contact = await fetch(`${API_URL}/by-email/${encodeURIComponent(email)}`, { headers }).then((res) => res.json());

// Step 2: Update the contact by ID (e.g., change email)
await fetch(`${API_URL}/${contact.data.id}`, {
  method: 'PUT',
  headers,
  body: JSON.stringify({ email: 'new-email@example.com' }),
});
```

## Related Endpoints

* **[Create or Update Contact](/api-reference/core-data/contacts/upsert)**: Upsert a contact by email or phone
* **[Update Contact by ID](/api-reference/core-data/contacts/update-by-id)**: Update a specific contact
* **[Delete Contact](/api-reference/core-data/contacts/delete)**: Soft-delete a contact


## OpenAPI

````yaml get /public/v1/contacts/by-email/{email}
openapi: 3.1.0
info:
  title: API Documentation
  description: Documentation for transactional and subscribe APIs
  version: 1.0.0
servers:
  - url: https://app.minimo.it
security:
  - bearerAuth: []
paths:
  /public/v1/contacts/by-email/{email}:
    servers:
      - url: https://api.minimo.it
    get:
      summary: Get contact by email
      description: >-
        Retrieve a contact's full data by their email address. Returns 404 if
        the contact does not exist or is soft-deleted.
      operationId: getContactByEmail
      parameters:
        - name: email
          in: path
          required: true
          description: Email address of the contact
          schema:
            type: string
            format: email
      responses:
        '200':
          description: Contact found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FullContactResponse'
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    examples:
                      - Contact not found
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: Python
          source: >-
            import requests


            url =
            'https://api.minimo.it/public/v1/contacts/by-email/customer@example.com'

            headers = {'Authorization': 'Bearer {{BEARER_TOKEN}}'}

            response = requests.get(url, headers=headers)

            print(response.json())
        - lang: JavaScript
          source: |-
            const response = await fetch(
              'https://api.minimo.it/public/v1/contacts/by-email/customer@example.com',
              { headers: { 'Authorization': 'Bearer {{BEARER_TOKEN}}' } }
            );
            const contact = await response.json();
            console.log(contact);
        - label: CLI
          lang: cURL
          source: |-
            curl --request GET \
              --url 'https://api.minimo.it/public/v1/contacts/by-email/customer@example.com' \
              --header 'Authorization: Bearer {{BEARER_TOKEN}}'
components:
  schemas:
    FullContactResponse:
      type: object
      properties:
        id:
          type: integer
          description: Contact ID
          examples:
            - 42
        email:
          type: string
          nullable: true
          description: Email address
          examples:
            - customer@example.com
        phone:
          type: string
          nullable: true
          description: Phone number in E.164 format
          examples:
            - '+393391234567'
        status:
          type: string
          nullable: true
          description: Contact status
          examples:
            - active
        source:
          type: string
          nullable: true
          description: Contact source
          examples:
            - API
        custom_fields:
          type: object
          nullable: true
          additionalProperties: true
          description: Custom field key-value pairs
        company:
          type: integer
          nullable: true
          description: Company ID
        deleted:
          type: boolean
          description: Whether the contact is soft-deleted
          examples:
            - false
        external_id:
          type: string
          nullable: true
          description: External system ID
        external_connection_id:
          type: integer
          nullable: true
          description: External connection ID
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: mn-API_CLIENT_ID-API_KEY

````