Skip to main content

​
Authentication

All API requests must include a valid API key in the X-API-Key header. 
curl -H "X-API-Key: bme_abc123def456ghi789jkl012mno345pqr678stu90v" \
  https://api-us1-1.benchmarkemail.com/api/contact-structure

​
Getting an API Key

  1. Log in to Benchmark Email with an Owner account. Only users with the Owner role can create and manage API keys.
  2. Navigate to Settings > API Keys.
  3. Click Create API Key.
  4. Enter a descriptive name (e.g., “Zapier Sync”, “CRM Integration”).
  5. Select the scopes (permissions) the key needs — see Scopes below.
  6. Optionally set an expiration date. If you skip this, the key never expires.
  7. Click Create and copy the key immediately.
The full API key is displayed only once at creation time. If you lose it, you can regenerate the key from the API Keys page (this invalidates the old key and issues a new one).

​
API Key Format

All Benchmark Email API keys start with the bme_ prefix, followed by 43 random characters: 
bme_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v
Total length: 47 characters (4-character prefix + 43 random characters).

​
Scopes

Each API key is granted one or more scopes that control which resources it can access. Scopes follow the {resource}:{access} format.

​
Available Scopes

ScopeDescription
contacts:readRead contacts, lists, contact structures, search contacts, export contacts, view contact events and history
contacts:writeCreate, update, and delete contacts and lists; update contact structures
campaigns:readRead campaigns and browse email templates
campaigns:writeCreate, update, delete, and duplicate campaigns
reports:readView dashboard summaries and email performance reports
domains:readView email sending domains

​
Write Implies Read

Granting write access for a resource automatically includes read access. For example, a key with contacts:write can also read contacts — you do not need to select both.

​
Principle of Least Privilege

Create keys with only the permissions they need. For example:
  • A reporting dashboard only needs reports:read.
  • A contact sync integration needs contacts:write (which includes read access).
  • A read-only data export tool needs contacts:read.

​
Scope Errors

If a request requires a scope that your key does not have, you will receive a 403 Forbidden response with a message identifying the required scope. See Errors for details.

​
Account Standing

API keys only work when your Benchmark Email account is in good standing. Keys are active when your account status is:
  • Open — normal active account
  • Pending Cancel — account is scheduled for cancellation but still active
Keys will stop working (returning 403 Forbidden) if your account is in any other status, such as suspended, past due, or terminated.

​
Key Lifecycle

Key StateBehavior
ActiveKey authenticates requests normally
InactiveKey has been deactivated by the owner; returns 401 Unauthorized
ExpiredKey’s expiration date has passed; returns 401 Unauthorized
DeletedKey has been permanently removed; returns 401 Unauthorized
You can deactivate and reactivate keys from the API Keys page without deleting them. This is useful for temporarily disabling an integration.

​
Example: Listing Contact Structures

curl -X GET \
  -H "X-API-Key: bme_abc123def456ghi789jkl012mno345pqr678stu90v" \
  https://api-us1-1.benchmarkemail.com/api/contact-structure
Response (200 OK): 
[
  {
    "_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "label": "Default Contacts",
    "keyName": "Email",
    "keyType": "email",
    "fields": [
      { "_id": "64a1b2c3d4e5f6a7b8c9d100", "label": "First Name", "dataType": "text" },
      { "_id": "64a1b2c3d4e5f6a7b8c9d101", "label": "Last Name", "dataType": "text" }
    ]
  }
]

​
Example: Creating a Contact

curl -X POST \
  -H "X-API-Key: bme_abc123def456ghi789jkl012mno345pqr678stu90v" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "john.smith@example.com",
    "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "fields": [
      { "_id": "64a1b2c3d4e5f6a7b8c9d100", "value": "John" },
      { "_id": "64a1b2c3d4e5f6a7b8c9d101", "value": "Smith" }
    ]
  }' \
  https://api-us1-1.benchmarkemail.com/api/contact
Response (200 OK): 
{
  "_id": "65a1b2c3d4e5f6a7b8c9d0e2",
  "key": "john.smith@example.com",
  "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "fields": [
    { "_id": "64a1b2c3d4e5f6a7b8c9d100", "value": "John" },
    { "_id": "64a1b2c3d4e5f6a7b8c9d101", "value": "Smith" }
  ],
  "status": { "primary": "active", "secondary": "confirmed" },
  "createdAt": "2026-03-30T14:22:00.000Z"
}
This request requires the contacts:write scope. If your key only has contacts:read, you will receive a 403 Forbidden error.

​
Next Steps