agentboxd-com

agentboxd-com Contacts API

Everyone your agents have exchanged mail with, with notes and labels, and the addresses your sends skip (suppressions).

GitHub OpenAPI

Operations 9

GET /v1/contacts List contacts #
GET /v1/contacts/{id} Get a contact #
PATCH /v1/contacts/{id} Update a contact #
DELETE /v1/contacts/{id} Delete a contact #
GET /v1/contacts/by-address/{address} Get a contact by email address #
POST /v1/contacts/delete Delete contacts in bulk #
GET /v1/contacts/domains Count contacts per domain #
GET /v1/suppressions List your suppressed addresses #
DELETE /v1/suppressions/{address} Remove a suppressed address #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/agentboxd-com/openapi/agentboxd-com-contacts-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/agentboxd-com:agentboxd-com-contacts-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

agentboxd-com-contacts-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Agentboxd Com Contacts API
  version: '1'
  contact:
    name: Agentboxd
    url: https://agentboxd.com
    email: hello@agentboxd.com
  description: 'Operations tagged Contacts across 2 of this provider''s published API definitions: agentboxd-com-openapi.json, agentboxd-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentboxd.com
security:
- apiKey: []
tags:
- name: Contacts
  description: Everyone your agents have exchanged mail with, with notes and labels, and the addresses your sends skip (suppressions).
paths:
  /v1/contacts:
    get:
      operationId: getContacts
      tags:
      - Contacts
      summary: List contacts
      description: '`?q=&label=&kind=&domain=&cursor=&limit=`. Newest `last_seen_at` first. `q` matches address or name. `kind` is one or more of `person`, `automated`, `sales`, `unknown`, comma-separated (every kind when left out). `domain` is the part after the @. `?metadata.=` filters.


        Permission: `contacts:read`.'
      x-permission: contacts:read
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          default: 25
          type: integer
          minimum: 1
          maximum: 100
      - name: q
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 200
      - name: label
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[^\s,]+$
      - name: kind
        in: query
        required: false
        schema:
          type: string
          pattern: ^(person|automated|sales|unknown)(,(person|automated|sales|unknown))*$
        description: 'Comma-separated kinds: person, automated, sales, unknown. Default: every kind.'
      - name: domain
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 253
        description: Only contacts at this domain (the part after the @), e.g. example.com.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/contacts/{id}:
    get:
      operationId: getContactsById
      tags:
      - Contacts
      summary: Get a contact
      description: 'The contact plus `recent_threads` (up to 10, across all inboxes).


        Permission: `contacts:read`.'
      x-permission: contacts:read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: patchContactsById
      tags:
      - Contacts
      summary: Update a contact
      description: '`{ name?, notes?, metadata?, add_labels?, remove_labels?, kind? }`. Notes up to 10,000 characters. A name or kind set here is never changed by later mail. See Contacts and memory.


        Permission: `contacts:write`.'
      x-permission: contacts:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  anyOf:
                  - type: string
                    maxLength: 200
                  - type: 'null'
                notes:
                  anyOf:
                  - type: string
                    maxLength: 10000
                  - type: 'null'
                metadata:
                  type: object
                  propertyNames:
                    type: string
                    pattern: ^[a-zA-Z0-9_.-]{1,64}$
                  additionalProperties:
                    anyOf:
                    - type: string
                      maxLength: 1000
                    - type: number
                    - type: boolean
                    - type: 'null'
                add_labels:
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 64
                    pattern: ^[^\s,]+$
                remove_labels:
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 64
                    pattern: ^[^\s,]+$
                kind:
                  type: string
                  enum:
                  - person
                  - automated
                  - sales
                  - unknown
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteContactsById
      tags:
      - Contacts
      summary: Delete a contact
      description: 'Deletes the contact → `204`. Its messages stay. `?forget=true` also stops mail from the address creating it again (the mail itself is not erased). Needs a workspace-wide key (inbox-scoped keys get `403`).


        Permission: `contacts:write`.'
      x-permission: contacts:write
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
      - name: forget
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
        description: 'true: also stop mail from the address creating the contact again (a keyed hash of it is kept). The mail stays.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/contacts/by-address/{address}:
    get:
      operationId: getContactsByAddressByAddress
      tags:
      - Contacts
      summary: Get a contact by email address
      description: 'Look a contact up by email address. 404 if you have never exchanged mail with it.


        Permission: `contacts:read`.'
      x-permission: contacts:read
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          minLength: 3
          maxLength: 320
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/contacts/delete:
    post:
      operationId: postContactsDelete
      tags:
      - Contacts
      summary: Delete contacts in bulk
      description: '`{ kind?: ["automated", …], domain?, forget?, dry_run? }` (kind, domain or both) → `{ matched, deleted, forgotten, has_more, dry_run }`. Deletes up to 1,000 matching contacts per call; `has_more` means call again. `dry_run: true` only counts. Workspace-wide keys only.


        Permission: `contacts:write`.'
      x-permission: contacts:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                kind:
                  minItems: 1
                  maxItems: 4
                  type: array
                  items:
                    type: string
                    enum:
                    - person
                    - automated
                    - sales
                    - unknown
                domain:
                  type: string
                  minLength: 1
                  maxLength: 253
                forget:
                  type: boolean
                dry_run:
                  type: boolean
              additionalProperties: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/contacts/domains:
    get:
      operationId: getContactsDomains
      tags:
      - Contacts
      summary: Count contacts per domain
      description: '`?kind=&limit=` → `{ data: [{ domain, contacts, last_seen_at }] }`: contacts counted per domain, most first, free-mail providers (Gmail, Outlook, Yahoo, iCloud, Proton…) left out. `limit` up to 200 (default 50).


        Permission: `contacts:read`.'
      x-permission: contacts:read
      parameters:
      - name: kind
        in: query
        required: false
        schema:
          type: string
          pattern: ^(person|automated|sales|unknown)(,(person|automated|sales|unknown))*$
        description: 'Comma-separated kinds: person, automated, sales, unknown. Default: every kind.'
      - name: limit
        in: query
        required: false
        schema:
          default: 50
          type: integer
          minimum: 1
          maximum: 200
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/suppressions:
    get:
      operationId: getSuppressions
      tags:
      - Contacts
      summary: List your suppressed addresses
      description: '`?reason=bounce|complaint|manual&q=&cursor=&limit=` → `{ data: [{ address, reason, created_at, expires_at }], next_cursor }`, newest first. Your workspace’s suppression list: addresses that bounced (`bounce`) or reported your mail as spam (`complaint`). Your sends to them are refused (`422 recipient_suppressed`). Only rows that apply now; other workspaces’ lists are never shown. `contacts:read`, workspace-wide keys only.


        Permission: `contacts:read`.'
      x-permission: contacts:read
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          default: 25
          type: integer
          minimum: 1
          maximum: 100
      - name: reason
        in: query
        required: false
        schema:
          type: string
          enum:
          - bounce
          - complaint
          - manual
      - name: q
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 320
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
  /v1/suppressions/{address}:
    delete:
      operationId: deleteSuppressionsByAddress
      tags:
      - Contacts
      summary: Remove a suppressed address
      description: 'Removes the address from your list, so you can write to it again → the removed row. A bounce or complaint needs `?confirm=true` (`409 confirmation_required` otherwise): sending again to an address that bounced or complained hurts your deliverability and can get sending paused. `404` when it isn’t on your list. Emits `suppression.removed` (who removed what). `contacts:write`, workspace-wide keys only.


        Permission: `contacts:write`.'
      x-permission: contacts:write
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          minLength: 3
          maxLength: 320
      - name: confirm
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.agentboxd.com
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Stable, machine-readable error code.
            message:
              type: string
              description: What happened and how to fix it, in plain words.
            details:
              description: 'The specifics: which recipient, which limit, until when.'
            docs_url:
              type: string
              format: uri
              description: 'For a refused send: its entry on "Why was my send refused?" (https://agentboxd.com/docs/send-refusals).'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An API key (`mr_…`), scoped to the workspace or one inbox, with a set of permissions.
externalDocs:
  description: API reference
  url: https://agentboxd.com/docs/api
x-refined-from:
- agentboxd-com-openapi.json
- agentboxd-com-openapi.json