Skip to content

External user certs info

GET/smime/users/external

Email Management API · SMIME

Get information about external users with S/MIME certificates.

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
email query string (email) No Filter by exact email address.
Must be 3–255 characters long.
emailStartsWith query string No Filter by email addresses that start with this prefix.
Must be 3–255 characters long.
certValidBefore query string (date) No Returns certificates that activate on or before this date.
certValidAfter query string (date) No Returns certificates that activate on or after this date.
certExpiryBefore query string (date) No Returns certificates that expire on or before this date.
certExpiryAfter query string (date) No Returns certificates that expire on or after this date.
certFingerprint query string No SHA-256 fingerprint of the certificate. This is not case sensitive.
Must match the pattern ^[a-fA-F0-9]{64}$. Must be exactly 64 characters long.
issuerCN query string No Filter by certificate issuer common name containing this text.
Must be 3–255 characters long.
pageFromKey query string No The key of the item from where to fetch a page.
pageSize query integer No The size of the page requested.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/email/v1/smime/users/external" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/email/v1/smime/users/external",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/email/v1/smime/users/external" -Headers $headers


package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/email/v1/smime/users/external", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/email/v1/smime/users/external", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — List of external users with their associated certificates.

Response fields

itemsarray of objectrequired
List of external users with certificate information.
External user with associated certificate information.
Show child attributesHide child attributes
emailstring (email)required
Email address of the user.
Must be 3–255 characters long.
associatedCertificatesInfoarray of objectrequired
List of certificates associated with the user.
Information about certificates associated with a user.
Show child attributesHide child attributes
fingerprintstringrequired
SHA-256 fingerprint of the certificate.
Must match the pattern ^[a-fA-F0-9]{64}$. Must be exactly 64 characters long.
certificateDetailsobjectrequired
Detailed information about a certificate.
Show child attributesHide child attributes
issuerstringrequired
Certificate issuer distinguished name.
Must be at most 255 characters long.
validFromstring (date-time)required
Certificate validity start date.
expiresAtstring (date-time)required
Certificate validity end date.
originstringrequired
Indicates how the certificate was obtained.
Must be one of: created, uploaded, extracted, unknown.
pagesobjectrequired
Show child attributesHide child attributes
fromKeystring
The key of the first item in the returned page.
nextKeystring
The key to use when fetching the next page.
sizeintegerrequired
The size of the page being returned.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
400 Invalid request.
401 Authentication required.
403 Authorization required.
500 Internal server error.
503 Server Unavailable.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "items": [
    {
      "email": "john.doe@sophos.com",
      "associatedCertificatesInfo": [
        {
          "fingerprint": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
          "certificateDetails": {
            "issuer": "C=UK,O=Sophos Limited,CN=Sophos Root CA",
            "validFrom": "2024-12-31T14:25:09Z",
            "expiresAt": "2029-12-31T18:30:12Z",
            "origin": "created"
          }
        }
      ]
    }
  ],
  "pages": {
    "fromKey": "string",
    "nextKey": "string",
    "size": 0,
    "maxSize": 0
  }
}

See the guide for a narrative walkthrough of this API.