Guide — SMIME

What you will build¶

You will configure S/MIME for a tenant and learn how to manage certificates for internal users, external users, and trusted certificate authorities (CAs).

Prerequisites¶

You must have a set of API credentials (service principal) to be able to call the S/MIME API. For more information refer to the appropriate quick start guide:

Sophos Partners: Read the Partner Getting Started guide first.
Enterprise customers: If you use Sophos Enterprise to manage multiple tenants, read the Organization Getting Started guide first.
Other customers: Read the Tenant Getting Started guide first.

Get credentials¶

Create API credentials for your Sophos Central account and use the access token in the Authorization: Bearer <access-token> header. Follow the applicable getting-started guide above for the credential-creation steps.

First authenticated call¶

Use your access token to retrieve the S/MIME configuration for the tenant:

curl --request GET \
  --url 'https://api-eu01.central.sophos.com/email/v1/smime/config' \
  --header 'X-Tenant-ID: <tenant-id>' \
  --header 'Authorization: Bearer <access-token>'

Replace eu01 with the tenant's data region.

Verify it worked¶

A successful request returns HTTP 200 and the current S/MIME configuration. If S/MIME has not been configured yet, continue with the configuration steps below.

What to do next¶

Set up the S/MIME configuration, then add the certificate authorities and user certificates your organization requires.

Overview¶

The rest of this guide provides the full configuration and certificate-management workflow.

Terminology¶

Before you use the S/MIME API, here are a few terms you should know:

S/MIME configuration: Per-tenant settings — whether S/MIME is enabled, whether to extract certificates from incoming mail, and who gets certificate-expiry notifications.
Internal CA: The certificate authority that signs certificates for your own (internal) users. Your tenant must have one internal CA at a time — you can either generate it or upload your own.
Internal user: One of your organization's mailboxes. You can generate a certificate for it or upload your own PKCS#12 bundle, signed by your internal CA.
External user: Someone outside your organization you exchange secured mail with. You upload their public certificate.
External (trusted) CA: A CA certificate you trust, used to validate certificates issued by other organizations.
Fingerprint: The SHA-256 fingerprint of a certificate. You use it to identify a specific certificate when downloading or deleting it.

Making API requests¶

You can make the API calls described in the next few sections using cURL. Follow the instructions on cURL's website to install this tool.

When using curl, a request to the S/MIME API has the following general form:

curl -X <method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>

The command includes the following placeholders:

<method>: The request method. For the S/MIME API, this is GET, POST, PATCH, or DELETE.
<tenant-id>: The ID of the tenant you want to configure.
<jwt>: The JWT access token returned when the IDP authenticates the service principal.
<data-region>: The regional API host in the data geography where the tenant data is located.
<path>: The request path for the API operation, for example email/v1/smime/config.

The API descriptions in this guide only specify the request method and path. To make an actual API request, you must expand this to the full form shown above.

All API requests return HTTP status codes 200 or 201 when successful.

Operations are permission-scoped — xgemail.smime:read, xgemail.smime:write, and xgemail.smime:delete. Make sure the service principal you authenticate with has been granted the scopes it needs for the calls you want to make.

Certificate security¶

Private keys are encrypted at rest and are never returned by any API call, including certificate downloads — only the public certificate comes back to you.

Certificate limits¶

The API is built to manage certificates at organization scale:

Up to 10,000 internal users and 10,000 external users per tenant.
Up to 2 active certificates per user — useful when rolling out a replacement certificate before an old one expires.
Up to 100 trusted external CA certificates.
One internal CA certificate per tenant at a time.

Rate limit¶

Each tenant gets generous daily allowances: 6,000 read calls and 3,000 write calls per day (create/update/delete), plus a separate allowance for configuration resets. If you exceed a limit, the API returns 400 Bad Request with error code TOO_MANY_REQUESTS — build your retry/backoff logic to check for that code.

Setting up S/MIME¶

Follow these steps to configure S/MIME for a tenant from scratch:

Create your internal CA — generate one or upload your own. Either call also creates a disabled S/MIME configuration automatically if you don't have one yet, so there's no separate setup call needed beforehand — this is the natural first step.
Turn S/MIME on with PATCH /config, setting smimeEnabled: true. This is also where you set extractCertificate and certExpiryNotificationEmailAddresses.
Add certificates for your internal users, either generated for you or from your own PKCS#12 bundle.
Add certificates for external users you want to exchange secured mail with — their certificate lets you send them encrypted mail and verify their signed mail: POST /users/external/certificate.
Trust external CAs, if you want messages signed by other organizations' CAs to be verified automatically: POST /cas/external/certificate.

This completes your tenant's S/MIME configuration. You can add, browse, and remove certificates as your organization changes.

If you'd rather set up your configuration (notification addresses, etc.) before creating an internal CA, you can call POST /config first with smimeEnabled: false — Just note that once a configuration exists, either from this call or automatically via step 1, POST /config will no longer be usable for that tenant (it only ever creates a new configuration). From then on, use PATCH /config for every subsequent change, including turning S/MIME on.

Configuration operations¶

Create S/MIME configuration¶

Use this API to create the S/MIME configuration for your tenant.

POST /email/v1/smime/config

Request:

{
  "smimeEnabled": false, //Set to false; enable S/MIME afterwards with PATCH once your internal CA is in place.
  "extractCertificate": true, //Whether to extract certificates from incoming messages.
  "certExpiryNotificationEmailAddresses": [ //Up to 5 tenant mailboxes to notify before certificates expire.
    "admin@domain.com",
    "alert@domain.com"
  ]
}

Response:

{
  "smimeEnabled": false,
  "extractCertificate": true,
  "certExpiryNotificationEmailAddresses": [
    "admin@domain.com",
    "alert@domain.com"
  ],
  "deleteToken": "a1b2c3d4" //Token to use as the path parameter for DELETE /config/{deleteToken}.
}

Update S/MIME configuration¶

Use this API to enable or disable S/MIME, and to change configuration settings.

PATCH /email/v1/smime/config

Request:

{
  "smimeEnabled": true, //Requires an internal CA certificate to already exist for the tenant.
  "certExpiryNotificationEmailAddresses": [ //Every address must be a real mailbox on your tenant.
    "admin@domain.com",
    "alert@domain.com"
  ]
}

Only the fields you include are updated; omit a field to leave it unchanged. To clear all notification addresses, send an empty list (or null) for certExpiryNotificationEmailAddresses.

Response:

{
  "smimeEnabled": true,
  "extractCertificate": true,
  "certExpiryNotificationEmailAddresses": [
    "admin@domain.com",
    "alert@domain.com"
  ],
  "deleteToken": "a1b2c3d4"
}

Get S/MIME configuration¶

Use this API to retrieve the current S/MIME configuration.

GET /email/v1/smime/config

Reset S/MIME configuration¶

Use this API to start fresh — It removes all certificates and private keys for the tenant and returns the configuration to a disabled state, ready to be reconfigured from step 1 without having to recreate the configuration record itself. Use the deleteToken returned from create/update/get as the path parameter.

Use this API with caution: it permanently deletes every certificate and private key the tenant has — internal CA, internal-user, external-user, and external CA — not just the configuration settings. Make sure you no longer need any of them before calling it.

DELETE /email/v1/smime/config/{deleteToken}

Response:

{
  "deleted": true
}

Internal CA operations¶

Create an internal CA¶

Use this API to make Sophos generate an internal CA certificate for you, using your organization's details. This certificate signs certificates you create for internal users.

POST /email/v1/smime/ca/internal

Request:

{
  "organizationName": "Sophos Limited",
  "organizationUnit": "Engineering",
  "locality": "Abingdon",
  "country": "GB", //Two-letter ISO 3166-1 country code.
  "email": "admin@sophos.com",
  "certExpiryDate": "2028-12-31" //Optional; defaults to 20 years from creation.
}

Response:

{
  "fingerprint": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "certificateDetails": {
    "issuer": "L=Abingdon,OU=Engineering,O=Sophos Limited,C=GB,CN=Sophos",
    "commonName": "Sophos",
    "subject": "L=Abingdon,OU=Engineering,O=Sophos Limited,C=GB,CN=Sophos",
    "validFrom": "2024-12-31T14:25:09Z",
    "expiresAt": "2028-12-31T18:30:12Z",
    "origin": "created"
  }
}

Certificates Sophos generates for you (as with this one) use RSA-2048 with SHA-512 signing — a strong, widely compatible default.

Upload an internal CA certificate¶

If you'd rather use your own CA, upload its PKCS#12 certificate-and-key bundle instead of generating one.

POST /email/v1/smime/ca/internal/certificate

Request:

{
  "password": "<PKCS12 password>", //Password to decrypt the PKCS12 bundle.
  "pkcs12": "<Base64-encoded PKCS12 bundle containing your CA certificate and private key>"
}

The bundle you receive from your CA will typically have your CA's own certificate first, followed by any certificates above it in the chain (e.g. the root CA that issued it) — which is what's expected here. Those chain certificates are automatically registered as trusted external CA certificates for you, so one upload takes care of both your CA certificate and its issuing chain. Uploads support RSA, EC, and DSA keys.

Get internal CA details¶

GET /email/v1/smime/ca/internal

Download the internal CA certificate¶

GET /email/v1/smime/ca/internal/certificate

Returns the PEM-encoded certificate as application/octet-stream.

Internal user certificate operations¶

Generate a certificate for an internal user¶

Use this API to make Sophos generate and sign a certificate for one of your mailboxes.

POST /email/v1/smime/users/internal

Request:

{
  "email": "john.doe@sophos.com",
  "certExpiryDate": "2028-12-31" //Optional; defaults to 20 years from creation.
}

Response:

{
  "email": "john.doe@sophos.com",
  "userName": "John Doe",
  "associatedCertificatesInfo": [
    {
      "fingerprint": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
      "certificateDetails": {
        "issuer": "L=Abingdon,OU=Engineering,O=Sophos Limited,C=GB,CN=Sophos",
        "validFrom": "2024-12-31T14:25:09Z",
        "expiresAt": "2028-12-31T14:25:09Z",
        "origin": "created"
      }
    }
  ]
}

Upload a certificate for an internal user¶

Use this API to upload your own PKCS#12 certificate-and-key bundle for a mailbox instead of making Sophos generate one.

POST /email/v1/smime/users/internal/certificate

Request:

{
  "email": "john.doe@sophos.com",
  "password": "<PKCS12 password>",
  "confirmSigningOnlyCert": false, //Only set to true if your certificate's key is signing/verification-only (e.g. DSA/EC) — most certificates don't need this.
  "pkcs12": "<Base64-encoded PKCS12 bundle containing the user's certificate and private key>"
}

The bundle you receive from your CA will typically have the end-entity (leaf) certificate first, which is what's expected here — Any additional CA certificates in the bundle (for example intermediate or root CA certificates) are automatically registered as trusted CA certificates. Uploading a certificate that's identical to one you already have on file for that email is rejected with response 409 Conflict; uploading the same certificate for a different email is treated as a new record.

Response:

{
  "items": [
    {
      "email": "john.doe@sophos.com",
      "userName": "John Doe",
      "associatedCertificatesInfo": [
        {
          "fingerprint": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
          "certificateDetails": {
            "issuer": "L=Abingdon,OU=Engineering,O=Sophos Limited,C=GB,CN=Sophos",
            "validFrom": "2024-12-31T14:25:09Z",
            "expiresAt": "2028-12-31T14:25:09Z",
            "origin": "uploaded"
          }
        }
      ]
    }
  ]
}

List or search internal user certificates¶

Use this API to list or search certificates for internal users.

GET /email/v1/smime/users/internal

Supported query parameters:

userName, email, emailStartsWith: Filter by user name (contains) or email (exact/prefix). Text filters are case-insensitive.
certValidBefore/certValidAfter, certExpiryBefore/certExpiryAfter: Filter by a date range (YYYY-MM-DD, from 2000-01-01 onward). If you use both, the ...After value must not be later than the ...Before value.
certFingerprint, issuerCN: Filter by certificate fingerprint or issuer (contains, case-insensitive).
pageFromKey, pageSize: Pagination — pass the nextKey from a response back as pageFromKey to fetch the next page; pageSize controls results per page (up to 200).

Response:

{
  "items": [
    {
      "email": "john.doe@sophos.com",
      "userName": "John Doe",
      "associatedCertificatesInfo": [
        {
          "fingerprint": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
          "certificateDetails": {
            "issuer": "L=Abingdon,OU=Engineering,O=Sophos Limited,C=GB,CN=Sophos",
            "validFrom": "2024-12-31T14:25:09Z",
            "expiresAt": "2029-12-31T18:30:12Z",
            "origin": "created"
          }
        }
      ]
    }
  ],
  "pages": {
    "size": 1, //Number of items on this page.
    "maxSize": 200, //Maximum page size supported.
    "nextKey": "eyJwYWdlIjoyLCJsYXN0SWQiOiIxMjM0NSJ9" //Pass as pageFromKey to get the next page.
  }
}

GET /users/external and GET /cas/external support the equivalent filters and pagination for external users and trusted CAs, respectively.

Download an internal user certificate¶

GET /email/v1/smime/users/internal/certificate/{fingerprint}

Returns the PEM-encoded certificate as application/octet-stream. If you originally uploaded a certificate chain, the download conveniently includes the full chain.

Remove an internal user certificate¶

Use this API to remove a specific certificate, identified by email and certFingerprint. If it's the user's only certificate, the user is removed from the S/MIME configuration listing.

DELETE /email/v1/smime/users/internal?email={email}&certFingerprint={certFingerprint}

Response:

{
  "deleted": true
}

External user certificate operations¶

Upload a certificate for an external user¶

Use this API to upload the public certificate of someone outside your organization.

POST /email/v1/smime/users/external/certificate

Request:

{
  "certificate": "-----BEGIN CERTIFICATE-----\n<Base64-encoded certificate>\n-----END CERTIFICATE-----",
  "confirmVerificationOnlyCert": false //Only set to true if your certificate's key is verification-only (e.g. DSA/EC) — most certificates don't need this.
}

Response:

{
  "items": [
    {
      "email": "external.user@example.com",
      "associatedCertificatesInfo": [
        {
          "fingerprint": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
          "certificateDetails": {
            "issuer": "L=Abingdon,OU=Engineering,O=Sophos Limited,C=GB,CN=Sophos",
            "validFrom": "2024-12-31T14:25:09Z",
            "expiresAt": "2028-12-31T14:25:09Z",
            "origin": "uploaded"
          }
        }
      ]
    }
  ]
}

List or search external user certificates¶

GET /email/v1/smime/users/external

Supports the same filters and pagination as internal user certificates (no userName filter, because external users aren't mailboxes on your tenant).

Download an external user certificate¶

GET /email/v1/smime/users/external/certificate/{fingerprint}

Returns the PEM-encoded certificate as application/octet-stream.

Remove an external user certificate¶

DELETE /email/v1/smime/users/external?email={email}&certFingerprint={certFingerprint}

Response:

{
  "deleted": true
}

External (trusted) CA operations¶

Upload a trusted CA certificate¶

Use this API to trust a CA certificate so messages signed by it are verified automatically.

POST /email/v1/smime/cas/external/certificate

Request:

{
  "certificate": "-----BEGIN CERTIFICATE-----\n<Base64-encoded certificate>\n-----END CERTIFICATE-----"
}

List or search trusted CA certificates¶

GET /email/v1/smime/cas/external

Supports the same filters and pagination as internal user certificates, using commonName in place of userName/email.

Download a trusted CA certificate¶

GET /email/v1/smime/cas/external/certificate/{fingerprint}

Returns the PEM-encoded certificate as application/octet-stream.

Remove a trusted CA certificate¶

DELETE /email/v1/smime/cas/external?certFingerprint={certFingerprint}

Response:

{
  "deleted": true
}

Working with groups of certificates: The delete and download endpoints act on one certificate at a time. To act on a whole group — for example, every trusted CA certificate from a particular issuer — first call the matching GET endpoint with a filter (e.g. issuerCN) to collect the fingerprints you want, then call the target endpoint once per fingerprint.

Conclusion¶

See the Email Management API reference for full request/response schemas, field constraints, and additional examples.