Benchmark Email

Benchmark Email Contact API

Contact related endpoints

GitHub OpenAPI
Business capability
Customer Data Management BC-420.10

Operations 10

GET /api/contact Get all contacts #
POST /api/contact Create a new contact #
GET /api/contact/events Get account contact events #
POST /api/contact/export Export contacts #
POST /api/contact/search Search for contacts #
DELETE /api/contact/{contactId} Delete a contact by id #
GET /api/contact/{contactId} Get a contact by id #
PATCH /api/contact/{contactId} Partial update a contact by id #
PUT /api/contact/{contactId} Update a contact by id #
GET /api/contact/{contactId}/events Get contact events #

Documentation

📖
Documentation
https://developers.benchmarkemail.io/
📖
APIReference
https://developers.benchmarkemail.io/api-reference
📖
GettingStarted
https://developers.benchmarkemail.io/introduction
📖
Authentication
https://artifacts.apis.io/benchmark-email/authentication/benchmark-email-authentication.yml
📖
RateLimits
https://artifacts.apis.io/benchmark-email/rate-limits/benchmark-email-rate-limits.yml

Specifications

⚙
OpenAPI
https://artifacts.apis.io/benchmark-email/openapi/benchmark-email-contact-api-openapi.yml

Other Resources

🔗
OAuthScopes
https://artifacts.apis.io/benchmark-email/scopes/benchmark-email-scopes.yml
🔗
ErrorCatalog
https://artifacts.apis.io/benchmark-email/errors/benchmark-email-problem-types.yml
🔗
Conventions
https://artifacts.apis.io/benchmark-email/conventions/benchmark-email-conventions.yml
🔗
DataModel
https://artifacts.apis.io/benchmark-email/data-model/benchmark-email-data-model.yml
🔗
ToolCrosswalk
https://artifacts.apis.io/benchmark-email/mcp/benchmark-email-tool-crosswalk.yml
🔗
AgentCard
https://artifacts.apis.io/benchmark-email/a2a/benchmark-email-a2a.yml
🔗
LLMsTxt
https://artifacts.apis.io/benchmark-email/llms/benchmark-email-llms.txt

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/benchmark-email:benchmark-email-contact-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

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

benchmark-email-contact-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  description: 'Public REST API for Benchmark Email.


    Authenticate every request by including your API key in the `X-API-Key` header.

    Each key is issued with one or more scopes that control which endpoints it may call.


    Rate limits: 60 requests per minute per account.

    Monthly quota: determined by your subscription plan.'
  title: Benchmark Email Contact API
  version: 1.0.0
servers:
- description: Your account's API base URL. Copy the full URL shown on Settings > API Keys in your Benchmark Email account and paste it here.
  url: '{apiBaseUrl}'
  variables:
    apiBaseUrl:
      default: ''
      description: Your account's API base URL. Copy it from Settings > API Keys in your Benchmark Email account.
security:
- apiKeyAuth: []
tags:
- description: Contact related endpoints
  name: Contact
paths:
  /api/contact:
    get:
      operationId: get_api_contact
      responses:
        '200':
          description: Successful
      security:
      - apiKeyAuth: []
      summary: Get all contacts
      tags:
      - Contact
      x-api-key-scope: contacts:read
    post:
      operationId: post_api_contact
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          description: Successfully created
      security:
      - apiKeyAuth: []
      summary: Create a new contact
      tags:
      - Contact
      x-api-key-scope: contacts:write
  /api/contact/events:
    get:
      description: Get all contact events for the account
      operationId: get_api_contact_events
      parameters:
      - description: Filter events by type
        example:
        - contact-created
        - contact-updated
        explode: false
        in: query
        name: types
        schema:
          items:
            enum:
            - contact-created
            - contact-updated
            - contact-update-failed
            - contact-unsubscribed
            - contact-reactivated
            - email-sent
            - email-bounced
            - email-delivered
            - email-delayed
            - email-rejected
            - email-complaint
            - email-opened
            - email-clicked
            - email-skipped
            type: string
          type: array
      - description: Filter events from the last N days (1-90). Defaults to 30 when omitted
        example: 30
        in: query
        name: pastDays
        required: false
        schema:
          default: 30
          maximum: 90
          minimum: 1
          type: integer
      - description: page number
        in: query
        name: page
        schema:
          minimum: 1
          type: integer
      - description: page size
        in: query
        name: size
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  records:
                    items:
                      properties:
                        contactId:
                          type: string
                        emailBounceDiagCode:
                          type: string
                        emailBounceSubType:
                          type: string
                        emailBounceType:
                          type: string
                        emailCampaignId:
                          type: string
                        emailCampaignName:
                          type: string
                        emailComplaintFeedbackType:
                          type: string
                        emailDelayType:
                          type: string
                        emailLinkId:
                          type: string
                        emailRejectReason:
                          type: string
                        emailSender:
                          type: string
                        emailSenderName:
                          type: string
                        emailSmtpResponse:
                          type: string
                        emailSubject:
                          type: string
                        emailTargetUrl:
                          type: string
                        emailTo:
                          type: string
                        importId:
                          type: string
                        importOriginalFileName:
                          type: string
                        source:
                          type: string
                        timestamp:
                          format: date-time
                          type: string
                        triggeredBy:
                          description: Present on contact-created/contact-updated events when a triggering user is recorded. The type and userId fields come from the event index.
                          properties:
                            type:
                              description: The type of actor that triggered the event (e.g. 'user', 'admin')
                              type: string
                            userId:
                              description: The ID of the user who triggered the event
                              type: string
                          type: object
                        type:
                          type: string
                      type: object
                    type: array
                  total:
                    type: integer
                type: object
          description: Contact events for the account
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
      summary: Get account contact events
      tags:
      - Contact
      x-api-key-scope: contacts:read
  /api/contact/export:
    post:
      operationId: post_api_contact_export
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          content:
            text/csv: {}
          description: Successful
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
      summary: Export contacts
      tags:
      - Contact
      x-api-key-scope: contacts:read
  /api/contact/search:
    post:
      operationId: post_api_contact_search
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  contacts:
                    items:
                      properties:
                        _id:
                          description: Id of the contact
                          type: string
                        contactStructureId:
                          description: Id of the contact structure
                          type: string
                        createdAt:
                          description: Date of creation
                          type: string
                        fields:
                          items:
                            properties:
                              _id:
                                description: Id of the field
                                type: string
                              value:
                                description: Value of the field
                                type: string
                            type: object
                          type: array
                        key:
                          description: Primary key of the contact
                          type: string
                        tags:
                          items:
                            properties:
                              _id:
                                description: Id of the tag
                                type: string
                            type: object
                          type: array
                        updatedAt:
                          description: Date of update
                          type: string
                      type: object
                    type: array
                  totalRecords:
                    description: Total number of records
                    type: number
                type: object
          description: Successful
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
      summary: Search for contacts
      tags:
      - Contact
      x-api-key-scope: contacts:read
  /api/contact/{contactId}:
    delete:
      operationId: delete_api_contact_by_contactId
      parameters:
      - in: path
        name: contactId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted
        '404':
          description: Contact not found
      security:
      - apiKeyAuth: []
      summary: Delete a contact by id
      tags:
      - Contact
      x-api-key-scope: contacts:write
    get:
      operationId: get_api_contact_by_contactId
      parameters:
      - in: path
        name: contactId
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully created
        '404':
          description: Contact not found
      security:
      - apiKeyAuth: []
      summary: Get a contact by id
      tags:
      - Contact
      x-api-key-scope: contacts:read
    patch:
      operationId: patch_api_contact_by_contactId
      parameters:
      - in: path
        name: contactId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          description: Successfully updated
        '404':
          description: Contact not found
      security:
      - apiKeyAuth: []
      summary: Partial update a contact by id
      tags:
      - Contact
      x-api-key-scope: contacts:write
    put:
      operationId: put_api_contact_by_contactId
      parameters:
      - in: path
        name: contactId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json: {}
      responses:
        '200':
          description: Successfully updated
        '404':
          description: Contact not found
      security:
      - apiKeyAuth: []
      summary: Update a contact by id
      tags:
      - Contact
      x-api-key-scope: contacts:write
  /api/contact/{contactId}/events:
    get:
      description: Get events for a contact
      operationId: get_api_contact_by_contactId_events
      parameters:
      - description: The contact id
        in: path
        name: contactId
        required: true
        schema:
          type: string
      - description: Filter events by type
        example:
        - contact-created
        - contact-updated
        explode: false
        in: query
        name: types
        schema:
          items:
            enum:
            - contact-created
            - contact-updated
            - contact-update-failed
            - contact-unsubscribed
            - contact-reactivated
            - email-sent
            - email-bounced
            - email-delivered
            - email-delayed
            - email-rejected
            - email-complaint
            - email-opened
            - email-clicked
            - email-skipped
            type: string
          type: array
      - description: page number
        in: query
        name: page
        schema:
          minimum: 1
          type: integer
      - description: page size
        in: query
        name: size
        schema:
          minimum: 1
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  records:
                    items:
                      properties:
                        contactId:
                          type: string
                        emailBounceDiagCode:
                          type: string
                        emailBounceSubType:
                          type: string
                        emailBounceType:
                          type: string
                        emailCampaignId:
                          type: string
                        emailCampaignName:
                          type: string
                        emailComplaintFeedbackType:
                          type: string
                        emailDelayType:
                          type: string
                        emailLinkId:
                          type: string
                        emailRejectReason:
                          type: string
                        emailSender:
                          type: string
                        emailSenderName:
                          type: string
                        emailSmtpResponse:
                          type: string
                        emailSubject:
                          type: string
                        emailTargetUrl:
                          type: string
                        emailTo:
                          type: string
                        importId:
                          type: string
                        importOriginalFileName:
                          type: string
                        source:
                          type: string
                        timestamp:
                          format: date-time
                          type: string
                        triggeredBy:
                          description: Present on contact-created/contact-updated events when a triggering user is recorded. The type and userId fields come from the event index.
                          properties:
                            type:
                              description: The type of actor that triggered the event (e.g. 'user', 'admin')
                              type: string
                            userId:
                              description: The ID of the user who triggered the event
                              type: string
                          type: object
                        type:
                          type: string
                      type: object
                    type: array
                  total:
                    type: integer
                type: object
          description: Events for the contact
        '400':
          description: Bad request
        '401':
          description: Unauthorized
      security:
      - apiKeyAuth: []
      summary: Get contact events
      tags:
      - Contact
      x-api-key-scope: contacts:read
components:
  securitySchemes:
    apiKeyAuth:
      description: API key authentication
      in: header
      name: X-API-Key
      type: apiKey
x-provenance:
  method: harvested
  publisher: Benchmark Email
  source: https://developers.benchmarkemail.io/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)