mailjunky-ai Contacts API

openapi: 3.2.0
info:
  title: MailJunky Contacts API
  version: 1.0.0
  description: 'The MailJunky API lets you send transactional emails, track user events, manage contacts, and build intelligent email workflows. All endpoints require API key authentication unless noted otherwise.


    ## SDK


    Install the official SDK for the easiest integration:


    ```bash

    npm install @mailjunky/sdk

    ```


    ```typescript

    import { MailJunky } from ''@mailjunky/sdk''

    const mailjunky = new MailJunky({ apiKey: ''mj_live_xxx'' })

    ```


    For browser-side event tracking:


    ```typescript

    import { initMailJunky } from ''@mailjunky/sdk/browser''

    const mj = initMailJunky({ apiKey: ''mj_pub_xxx'' })

    ```


    ## Authentication


    Authenticate by including your API key in the `Authorization` header:


    ```

    Authorization: Bearer mj_live_your_api_key

    ```


    You can also use the `X-API-Key` header. Public keys (`mj_pub_*`) are restricted to event tracking only.


    ## Rate Limits


    All responses include rate limit headers:

    - `X-RateLimit-Limit` - Requests allowed per window

    - `X-RateLimit-Remaining` - Requests remaining

    - `X-RateLimit-Reset` - Window reset time (unix timestamp)

    - `Retry-After` - Seconds to wait (when rate limited)


    ## Base URL


    ```

    https://www.mailjunky.ai/api/v1

    ```'
  contact:
    name: MailJunky Support
    url: https://www.mailjunky.ai
    email: support@mailjunky.ai
servers:
- url: https://www.mailjunky.ai/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Contacts
  description: Manage your contact lists and subscriber data
paths:
  /contacts:
    get:
      operationId: listContacts
      summary: List contacts
      description: 'Retrieve a paginated list of contacts. Supports filtering by email, tag, and status.


        **Rate limit:** 100 requests/minute


        **Permissions required:** `analytics:read`'
      tags:
      - Contacts
      x-codeSamples:
      - lang: JavaScript
        label: MailJunky SDK
        source: "import { MailJunky } from '@mailjunky/sdk'\n\nconst mailjunky = new MailJunky({ apiKey: 'mj_live_xxx' })\n\nconst { data, pagination } = await mailjunky.contacts.list({\n  page: 1,\n  limit: 25,\n  status: 'active',\n  tag: 'customer'\n})\n\nconsole.log(`${pagination.total} contacts found`)\ndata.forEach(c => console.log(c.email))"
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Page number
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        description: Results per page (max 100)
      - name: email
        in: query
        schema:
          type: string
        description: Filter by email (case-insensitive search)
      - name: tag
        in: query
        schema:
          type: string
        description: Filter by tag (exact match)
      - name: status
        in: query
        schema:
          type: string
          enum:
          - ACTIVE
          - UNSUBSCRIBED
          - BOUNCED
          - COMPLAINED
        description: Filter by contact status
      responses:
        '200':
          description: Paginated list of contacts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createContact
      summary: Create or update a contact
      description: 'Create a new contact or update an existing one (upsert by email). If a contact with the same email already exists, it will be updated.


        **Rate limit:** 100 requests/minute


        **Permissions required:** `analytics:read`'
      tags:
      - Contacts
      x-codeSamples:
      - lang: JavaScript
        label: MailJunky SDK
        source: "import { MailJunky } from '@mailjunky/sdk'\n\nconst mailjunky = new MailJunky({ apiKey: 'mj_live_xxx' })\n\nconst contact = await mailjunky.contacts.create({\n  email: 'user@example.com',\n  first_name: 'Alice',\n  last_name: 'Smith',\n  tags: ['customer', 'premium'],\n  properties: { plan: 'pro', company: 'Acme Inc' }\n})\n\nconsole.log(contact.id)"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateContactRequest'
            example:
              email: user@example.com
              first_name: Alice
              last_name: Smith
              tags:
              - customer
              - premium
              properties:
                plan: pro
                company: Acme Inc
      responses:
        '200':
          description: Contact created or updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactBasic'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /contacts/{id}:
    get:
      operationId: getContact
      summary: Get a contact
      description: 'Retrieve a single contact by ID with full engagement statistics.


        **Rate limit:** 100 requests/minute


        **Permissions required:** `analytics:read`'
      tags:
      - Contacts
      x-codeSamples:
      - lang: JavaScript
        label: MailJunky SDK
        source: 'import { MailJunky } from ''@mailjunky/sdk''


          const mailjunky = new MailJunky({ apiKey: ''mj_live_xxx'' })


          const contact = await mailjunky.contacts.get(''contact_id'')


          console.log(contact.email, contact.status)

          console.log(`Sent: ${contact.emails_sent}, Opened: ${contact.emails_opened}`)'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Contact ID
      responses:
        '200':
          description: Contact details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contact'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateContact
      summary: Update a contact
      description: 'Update an existing contact''s fields. Only provided fields will be updated.


        **Rate limit:** 100 requests/minute


        **Permissions required:** `contacts:write`'
      tags:
      - Contacts
      x-codeSamples:
      - lang: JavaScript
        label: MailJunky SDK
        source: "import { MailJunky } from '@mailjunky/sdk'\n\nconst mailjunky = new MailJunky({ apiKey: 'mj_live_xxx' })\n\nconst updated = await mailjunky.contacts.update('contact_id', {\n  first_name: 'Alice',\n  tags: ['customer', 'vip'],\n  properties: { plan: 'enterprise' }\n})\n\nconsole.log(updated.email, updated.tags)"
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Contact ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContactRequest'
            example:
              first_name: Alice
              tags:
              - customer
              - vip
              properties:
                plan: enterprise
      responses:
        '200':
          description: Contact updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactBasic'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: A contact with this email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteContact
      summary: Delete a contact
      description: 'Permanently delete a contact by ID.


        **Rate limit:** 100 requests/minute


        **Permissions required:** `contacts:write`'
      tags:
      - Contacts
      x-codeSamples:
      - lang: JavaScript
        label: MailJunky SDK
        source: 'import { MailJunky } from ''@mailjunky/sdk''


          const mailjunky = new MailJunky({ apiKey: ''mj_live_xxx'' })


          await mailjunky.contacts.delete(''contact_id'')

          console.log(''Contact deleted'')'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Contact ID
      responses:
        '200':
          description: Contact deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                    const: true
              example:
                deleted: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /contacts/batch:
    post:
      operationId: batchImportContacts
      summary: Batch import contacts
      description: 'Import up to 1,000 contacts in a single request. Contacts are upserted by email -- existing contacts will be updated, new ones created.


        **Rate limit:** 100 requests/minute


        **Permissions required:** `analytics:read`'
      tags:
      - Contacts
      x-codeSamples:
      - lang: JavaScript
        label: MailJunky SDK
        source: "import { MailJunky } from '@mailjunky/sdk'\n\nconst mailjunky = new MailJunky({ apiKey: 'mj_live_xxx' })\n\nconst result = await mailjunky.contacts.batch({\n  contacts: [\n    { email: 'alice@example.com', first_name: 'Alice', tags: ['customer'] },\n    { email: 'bob@example.com', first_name: 'Bob', tags: ['lead'] }\n  ]\n})\n\nconsole.log(`Created: ${result.created}, Updated: ${result.updated}`)"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchContactRequest'
            example:
              contacts:
              - email: alice@example.com
                first_name: Alice
                tags:
                - customer
              - email: bob@example.com
                first_name: Bob
                tags:
                - lead
      responses:
        '200':
          description: Batch import results
          content:
            application/json:
              schema:
                type: object
                properties:
                  created:
                    type: integer
                    description: Number of new contacts created
                  updated:
                    type: integer
                    description: Number of existing contacts updated
                  failed:
                    type: array
                    items:
                      type: object
                      properties:
                        email:
                          type: string
                        error:
                          type: string
                    description: Contacts that failed to import
              example:
                created: 1
                updated: 1
                failed: []
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    UpdateContactRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        phone:
          type: string
        properties:
          type: object
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - active
          - unsubscribed
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        has_more:
          type: boolean
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        statusMessage:
          type: string
        message:
          type: string
        data:
          type: object
          description: Additional error details (e.g. validation errors)
          properties:
            fieldErrors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
            formErrors:
              type: array
              items:
                type: string
    ContactBasic:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        properties:
          type: object
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        status:
          type: string
        created_at:
          type: string
          format: date-time
    Contact:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        properties:
          type: object
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - active
          - unsubscribed
          - bounced
          - complained
        emails_sent:
          type: integer
        emails_opened:
          type: integer
        emails_clicked:
          type: integer
        last_email_sent_at:
          type: string
          format: date-time
          nullable: true
        last_opened_at:
          type: string
          format: date-time
          nullable: true
        unsubscribed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CreateContactRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        phone:
          type: string
        properties:
          type: object
          additionalProperties: true
          description: Custom properties
        tags:
          type: array
          items:
            type: string
          description: Tags for segmentation
    BatchContactRequest:
      type: object
      required:
      - contacts
      properties:
        contacts:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            $ref: '#/components/schemas/CreateContactRequest'
          description: Array of 1-1,000 contacts to import
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 404
            statusMessage: Not Found
            message: Resource not found
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 401
            statusMessage: Unauthorized
            message: Invalid or missing API key
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 403
            statusMessage: Forbidden
            message: This API key does not have the required permission
    ValidationError:
      description: Request validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            statusCode: 400
            message: Validation failed
            data:
              fieldErrors:
                to:
                - Invalid email
              formErrors: []
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Use your `mj_live_*` or `mj_pub_*` key as the bearer token.
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Alternative: pass your API key via the X-API-Key header.'
x-scalar-sdk-installation:
- lang: Node
  label: MailJunky SDK
  description: 'Install the official **MailJunky SDK** from npm:'
  source: npm install @mailjunky/sdk
- lang: JavaScript
  label: Browser SDK
  description: 'For browser-side event tracking:'
  source: npm install @mailjunky/sdk