To generate your API Key follow the guide at mxHERO V3 API Key

Overview

The S/MIME Certificate Management API provides comprehensive functionality for managing digital certificates and email accounts in an organization. This system enables secure email operations including signing, encryption, decryption, and signature verification using S/MIME standards.

API Documentation: https://prod-mxhero-static-content-bucket.s3.us-east-1.amazonaws.com/site/smime-api.html

Core Entities

1. Email Accounts (EmailAccount)

An EmailAccount represents an email address within your organization and its associated S/MIME certificates. It tracks:

• email: The email address (primary key)
• organizationId: Your organization identifier
• primaryCertificateId: The active certificate used for signing and decryption
• certificateHistory: List of all certificates associated with this email
• createdAt/updatedAt: Timestamps for tracking changes

Key Points:

• Each email account can have multiple certificates in its history
• Only one primary certificate is active at any time
• The primary certificate is used for signing outgoing emails and decrypting incoming emails
• External email accounts can be created but won't be used for signing (only for validation and encryption)

2. Certificates (StoredCertificate)

A StoredCertificate represents an S/MIME digital certificate that can be uploaded in two formats:

PEM Certificates (Public Key Only)

• Contains only the public key portion
• Used for encrypting emails to recipients
• Used for verifying signatures from senders
• Cannot be used for signing or decrypting

P12/PKCS12 Certificates (Public + Private Key)

• Contains both public and private keys
• Password protected during upload (original password is **never stored** by MXHero)
• The P12 certificate is **automatically re-encrypted** with a new internal password for secure storage
• Used for signing emails (requires private key)
• Used for decrypting emails (requires private key)
• Can also encrypt and verify like PEM certificates

API Workflow

Step 1: Upload Certificates

Before creating email accounts, upload the necessary certificates:

Upload P12 Certificate (with private key in BASE64 format)

curl -X POST \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/certificates/upload/p12" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "certificateData": "MIIJKQIBAzCCCO8G...",
    "friendlyName": "John Doe Signing Certificate",
    "password": "your-p12-password"
  }'

Upload PEM Certificate (public key only)

curl -X POST \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/certificates/upload/pem" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "certificateData": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    "friendlyName": "External Partner Certificate"
  }'

Response: Returns a StoredCertificate object with a unique certificateId that you'll use in subsequent operations.

Step 2: Create Email Accounts

Create Internal Email Account (for signing/decrypting)

curl -X POST \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/email-accounts" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@yourcompany.com",
    "primaryCertificateId": "cert-id-from-step1",
    "certificateHistory": ["cert-id-from-step1"]
  }'

Create External Email Account (for encryption/verification only)

curl -X POST \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/email-accounts" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "partner@external-company.com",
    "primaryCertificateId": "external-cert-id",
    "certificateHistory": ["external-cert-id"]
  }'

Step 3: Manage Certificate Associations

Set Primary Certificate

curl -X POST \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/email-accounts/{email}/certificates/{certificateId}/set-primary" \
  -H "Authorization: Bearer {your-token}"

Add Certificate to History

curl -X POST \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/email-accounts/{email}/certificates/{certificateId}/add-to-history" \
  -H "Authorization: Bearer {your-token}"

Certificate Usage Scenarios

Scenario 1: Internal User Signing Emails

1. Upload P12 certificate with private key
2. Create email account with this certificate as primary
3. System uses this certificate to sign outgoing emails

Scenario 2: Encrypting to External Recipients

1. Upload PEM certificate (public key) of external recipient
2. Create email account for external recipient
3. System uses this certificate to encrypt emails to them

Scenario 3: Certificate Renewal

1. Upload new P12 certificate
2. Add new certificate to account history
3. Set new certificate as primary
4. Old certificate remains in history for historical verification

Important Considerations

Primary Certificate Requirements

• Must have private key for signing and decryption operations
• Only accounts managed by the organization can sign

Certificate Types and Capabilities

Security Best Practices

1. Store P12 passwords securely
2. Use strong passwords for P12 certificates
3. Regularly rotate certificates
4. Keep certificate history for audit trails
5. Monitor certificate expiration dates

Common API Operations

List Email Accounts

curl -X GET \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/email-accounts?limit=20&offset=0" \
  -H "Authorization: Bearer {your-token}"

Get Specific Email Account

curl -X GET \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/email-accounts/{email}" \
  -H "Authorization: Bearer {your-token}"

List Certificates

curl -X GET \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/certificates?limit=20&offset=0" \
  -H "Authorization: Bearer {your-token}"

Get Certificate Details

curl -X GET \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/certificates/{certificateId}" \
  -H "Authorization: Bearer {your-token}"

Update Certificate Information

curl -X PATCH \
  "https://api.mxhero.com/v3/organizations/{organizationId}/smime/certificates/{certificateId}" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "friendlyName": "Updated Certificate Name",
    "description": "Updated description"
  }'

Error Handling

The API returns standard HTTP status codes:

• 200: Success
• 201: Created
• 400: Bad Request (validation errors)
• 404: Not Found
• 409: Conflict (duplicate email account)
• 500: Server Error

Error responses include details:

{
  "error": "Validation failed",
  "message": "primaryCertificateId must be present in certificateHistory",
  "timestamp": "2025-01-15T10:30:00Z"
}