Order secure email certificate

NOTICE: Upcoming endpoint changes

Starting July 10, 2025 17:00 UTC, DigiCert® will no longer accept S/MIME certificate requests that use the legacy certificate profile (issuance of any pending legacy orders also ends July 10, 2025).

After the cut-off each Secure Email product behaves as follows:

*1 You can update the default profile on the CertCentral product settings page after July 10, 2025.

Quick checklist

Use this checklist to make sure you are ready for these changes.

Request parameter changes

Example request body (truncated)

Mailbox-validated (Individual) – no name fields

{
  "certificate": {
    "emails": ["alice@example.com"]
    /* profile_type omitted → "multipurpose" */
  }
}

Sponsor-validated – name common name

{
  "certificate": {
    "emails": ["alice@example.com"],
    "profile_type": "strict",
    "common_name_indicator": "email_address",
    "individual": {
      "first_name": "Alice",
      "last_name": "Example"
    }
  }
}

For complete details, see DigiCert Knowledge Base: New certificate profile requirements for public secure email (S/MIME) certificates.

• Secure Email for Individual Mailbox:secure_email_mailbox Certificate for individuals to sign and secure emails. These certificates do not require organization validation.
• Secure Email for Employee:secure_email_sponsor Certificate for individuals within an organization to sign and secure emails.
• Secure Email for Organization:secure_email_organization Certificate to sign and secure emails for an organization.

Example requests and responses

• cURL (secure_email_mailbox)
• cURL (secure_email_organization)
• cURL (secure_email_sponsor)

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/secure_email_mailbox' \
  --header 'Content-Type: application/json' \
  --header 'X-DC-DEVKEY: {{api_key}}' \
  --data-raw '{
  "certificate": {
    "profile_type": "multipurpose",
    "emails": [
      "john.doe@example.com"
    ],
    "csr": "{{csr}}",
    "common_name_indicator": "email_address",
    "usage_designation": {
      "primary_usage": "dual_use",
      "additional_usages": [
        "non_repudiation"
      ]
    },   
  },
  "skip_approval": true,
  "order_validity": {
    "years": 1
  },
  "payment_method": "balance"
}'

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/secure_email_organization' \
  --header 'Content-Type: application/json' \
  --header 'X-DC-DEVKEY: {{api_key}}' \
  --data-raw '{
  "certificate": {
    "profile_type": "multipurpose",
    "individual": {
      "first_name": "John",
      "last_name": "Doe"
    },
    "emails": [
      "john.doe@example.com"
    ],
    "csr": "{{csr}}",
    "common_name_indicator": "organization_name",
    "usage_designation": {
      "primary_usage": "dual_use",
      "additional_usages": [
        "non_repudiation"
      ]
    },  
  },
  "skip_approval": true,
  "organization": {
    "id": {{organization_id}}
  },
  "order_validity": {
    "years": 1
  },
  "subject": {      
      "include_email": true
  },
  "payment_method": "balance"
}'

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/secure_email_sponsor' \
  --header 'Content-Type: application/json' \
  --header 'X-DC-DEVKEY: {{api_key}}' \
  --data-raw '{
  "certificate": {
    "profile_type": "multipurpose",
    "individual": {
      "first_name": "John",
      "last_name": "Doe"
    },
    "emails": [
      "john.doe@example.com"
    ],
    "csr": "{{csr}}",
    "signature_hash": "sha256",
    "common_name_indicator": "given_name_surname",
    "usage_designation": {
      "primary_usage": "dual_use",
      "additional_usages": [
        "non_repudiation"
      ]
    }   
  },
  "skip_approval": true,
  "organization": {
    "id": "2030405"
  },
  "order_validity": {
    "years": 1
  },
  "subject": {      
      "include_given_name_surname": true,
      "include_email": true,
      "include_pseudonym": false   
  },
  "payment_method": "balance"
}'

• 201 Created (skip_approval)
• 201 Created (one-step approval)
• 201 Created (two-step approval)
• 201 Created (auto approval)

{
  "id": 123456,
  "certificate_id": 123456
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "pending"
    }
  ]
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "submitted"
    }
  ]
}

{
  "id": 112233,
  "requests": [
    {
      "id": 113,
      "status": "approved"
    }
  ],
  "certificate_id": 113
}

Certificate uses

When creating an order for a Secure Email certificate, you must choose a primary use for the certificate. The primary use determines the values DigiCert includes in the certificate’s key usage (KU) extension.

Optionally, you may choose one or more additional uses for the certificate. If you do, DigiCert includes values for the additional uses in the certificate’s KU and extended key usage (EKU) extensions.

To choose primary and additional uses for a certificate, use the primary_usage and additional_usages fields in the usage_designation object. Place the usage_designation object inside the certificate object at the root of your request body. For example:

{
  "certificate": {
    "usage_designation": {
      "primary_usage": "signing",
      "additional_usages": [
        "non_repudiation",
        "client_auth"
      ]
    },
    ...
  },
  ...
}

Primary uses

Choosing a primary use is required. All Secure Email certificates support these primary uses:

Additional uses

Including additional uses is optional. The additional uses you may choose depend on two factors:

• Certificate primary use
• Key type (RSA or ECC) of the private key that was used to generate the certificate signing request (CSR)

RSA CSR

If you generated the CSR in your request with an RSA private key, or if you will generate the CSR in the browser after creating the order, you can add one or more of these uses to the certificate:

ECC CSR

If you generated the CSR in your request with an ECC private key, you can add one or more of these uses to the certificate:

Common name value

With Secure Email for Employee and Secure Email for Organization certificates, you choose which value to use as the common name on the certificate.

To choose a value for the common name, use the common_name_indicator parameter in the certificate object at the root of your request body. Each Secure Email product allows different common name values. These values are:

Optional subject DN attributes

All three Secure Email certificates allow you to include the secured email address in the subject distinguished name (DN) extension on the issued certificate. Additionally, Secure Email for Employee certificates allow you to include the title, pseudonym, and serial number subject DN attributes.

To get a certificate with these subject DN attributes, include the subject object at the root of the request body. The contents of the subject object determine which attributes appear alongside the certificate’s common name and organization information in the subject DN.

Supported subject DN attributes and examples for each S/MIME certificate product are provided below:

• secure_email_individual
• secure_email_organization
• secure_email_sponsor

{
  "certificate": {
    "emails": [
      "example@example.com"
    ],
    ...
  },
  ...
  "subject": {
    "include_email": true
  },
  ...
}

In this example, the subject DN email attribute will include the email address *example@example.com*.

{
  "certificate": {
    "emails": [
      "example@example.com"
    ],
    ...
  },
  ...
  "subject": {
    "include_email": true
  },
  ...
}

In this example, the subject DN email attribute will include the email address *example@example.com*.

{
  "certificate": {
    "emails": [
      "example@example.com"
    ]
  },
  "common_name_indicator": "given_name_surname",
  "individual": {
    "given_name": "John",
    "surname": "Doe"
    }
    ...
  },
  "subject": {
    "include_given_name_surname": true,
    "include_email": true,
    "include_pseudonym": false,
    "serial_number": "ABC-123",
    "job_title": "SRE"
  },
  ...
}

In this example, the value of each subject DN attributes will be as follows:

- Subject DN email: `example@example.com`
- Subject DN title: `SRE`
- Subject DN serial number: `ABC-123`

Optional subject alternative name (SAN) attributes

Secure Email for Employee certificates allow you to include the user principle name (UPN) attribute in the certificate’s SAN extension.

To include the UPN SAN attribute in the certificate, include the user_principle_name array in the certificate object at the root of the request body. This array can have a single item with a character limit of 255.

secure_email_sponsor

{
  "certificate": {
    "user_principle_name": [
      "example"
    ]
    ...
  },
  ...
}

Email address validation

Before issuing your certificate, DigiCert must verify you control the email addresses on the order. The verification process depends on the product type.

Secure Email for Individual Mailbox

When you order this product, DigiCert sends validation emails to each email address in the emails array. Before DigiCert can issue the certificate, each email recipient must follow the instructions in the email to prove they control the mailbox.

Secure Email for Employee and Secure Email for Organization

For these products, you must complete a domain control validation (DCV) check for each unique email domain in the emails array.

When you create the order, CertCentral adds any new domains submitted for validation to your CertCentral account. Alternatively, you can add the domains to your account and validate them before creating the certificate order. Learn more about DCV methods.

Request parameters

Response parameters