Order Secure Email (S/MIME) certificate

POST https://www.digicert.com/services/v2/order/certificate/{{product_name_id}}

Use this endpoint to create an order for a Secure Email (S/MIME) certificate. In the request URL, replace {{product_name_id}} with the product identifier for the certificate you want to order:

Secure Email for Individual: secure_email_mailbox
Certificate for individuals to sign and secure emails. These certificates do not require organization validation.
Secure Email for Business: 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

Example 1. cURL (secure_email_mailbox)

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": {
    "emails": [
      "jane.doe@example.com"
    ],
    "csr": "{{csr}}",
    "usage_designation": {
      "primary_usage": "dual_use",
      "additional_usages": [
        "non_repudiation"
      ]
    }
  },
  "skip_approval": true,
  "order_validity": {
    "years": 1
  },
  "payment_method": "balance"
}'

Example 2. cURL (secure_email_organization)

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": {
    "emails": [
      "jane.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
  },
  "payment_method": "balance"
}'

Example 3. cURL (secure_email_sponsor)

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": {
    "individual": {
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "emails": [
      "jane.doe@example.com"
    ],
    "csr": "{{csr}}",
    "common_name_indicator": "given_name_surname",
    "usage_designation": {
      "primary_usage": "dual_use",
      "additional_usages": [
        "non_repudiation"
      ]
    }
  },
  "skip_approval": true,
  "organization": {
    "id": {{organization_id}}
  },
  "order_validity": {
    "years": 1
  },
  "payment_method": "balance"
}'

Example 4. 201 Created (skip_approval)

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

Example 5. 201 Created (one-step approval)

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

Example 6. 201 Created (two-step approval)

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

Example 7. 201 Created (auto approval)

{
  "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.

Note

All products described on this page are S/MIME certificates. For S/MIME certificates, the EKU extension includes email protection (id-kp-emailProtection) by default.

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:

`primary_usage` value	Description	Key usage
`signing`	Email signing only	`digitalSignature`
`key_management`	Email encryption only	`keyEncipherment`
`dual_use`	Email signing and encryption	`keyEncipherment` and `digitalSignature`

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:

`additional_usages` values	Description	Supported on certificates with these primary uses	Key usages	Extended key usages
`non_repudiation`	Non-repudiation	`signing` `dual_use`	`nonRepudiation`
`data_encipherment`	Data encipherment	`key_management` `dual_use`	`dataEncipherment`
`client_auth`	Client authentication	`signing` `key_management` `dual_use`		`id-kp-clientAuth`

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:

Important

To use an ECC CSR, you must include the CSR in your request to create an order, instead of generating the CSR in the browser after the order is created.

For browser-generated certificates, DigiCert uses an RSA algorithm, SHA256 signature hash, and a 2048-bit key length CSR. To get a certificate with a different key length, signature hash, or algorithm, you must include a CSR with your request.

`additional_usages` value	Description	Supported on certificates with these primary uses	Key usages	Extended key usages
`non_repudiation`	Non-repudiation	`signing` `dual_use`	`nonRepudiation`
`encipher_only` ^*	Key agreement restricted to enciphering data	`key_management` `dual_use`	`keyAgreement` and `encipherOnly`
`decipher_only` ^*	Key agreement restricted to deciphering data	`key_management` `dual_use`	`keyAgreement` and `decipherOnly`
`client_auth`	Client authentication	`signing` `key_management` `dual_use`		`id-kp-clientAuth`

Note

^*The encipher_only and decipher_only values are mutually exclusive in the additional_usages array.

Common name value

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

Note

For Secure Email for Individual (secure_email_mailbox) certificates, the common name value is always the first email address you provide in the emails array on the certificate object.

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:

Value	Description	Products that allow this common name value
`email_address`	The common name is the first email in the `emails` array.	Secure Email for Business Secure Email for Organization
`given_name_surname`	The common name is the `first_name` + `last_name` from the `individual` object.^*	Secure Email for Business
`pseudonym`	The common name is the `pseudonym` from the `individual` object.^*	Secure Email for Business
`organization_name`	The common name is the `name` + `assumed_name` of the `organization` on the order.	Secure Email for Organization

Warning

^*By using the given_name_surname or pseudonym as the common name on a Secure Email for Business certificate, you attest the individual is a valid employee or representative of the company and included in official company registries. Invalid names can be rejected or revoked without notice.

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 Business 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 document signing product are provided below:

Example 8. secure_email_individual

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
  },
  ...
}

Example 9. secure_email_organization

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
  },
  ...
}

Example 10. secure_email_sponsor

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

Subject DN email: example@example.com
Subject DN pseudonym: John Doe (from the individual object)
Subject DN title: SRE
Subject DN serial number: ABC-123

{
  "certificate": {
    "emails": [
      "example@example.com"
    ],
    "individual": {
      "pseudonym": "John Doe"
    }
    ...
  },
  ...
  "subject": {
    "include_pseudonym": true,
    "include_email": true,
    "serial_number": "ABC-123",
    "job_title": "SRE"
  },
  ...
}

Optional subject alternative name (SAN) attributes

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

Note

CertCentral does not support the UPN SAN attribute for Secure Email for Individual or Secure Email for Organization certificates.

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.

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

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 Business 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.

Note

Orders for Secure Email for Business/Organization certificates should only include email addresses with domains owned by your organization. DigiCert rejects orders for email addresses from some of the most common public email service providers, such as Gmail, Outlook, Yahoo, Hotmail, and MSN.

To order a certificate for an email address from a public email service provider:

If the organization does not own the public email service provider and cannot complete a DCV check for the email domain, order a Secure Email for Individual certificate, instead.
If the organization on the order owns the public email service provider, validate the domain in your CertCentral account before submitting the order request.

Request parameters

Name	Req/Opt	Type	Description
certificate	required	object	Certificate details.
.. csr	optional	string	Certificate signing request (CSR) or public key. Format the CSR/public key as a base64-encoded string without line breaks or escape characters. Include the PEM headers and footers (such as `-----BEGIN CERTIFICATE REQUEST-----...` and `...-----END CERTIFICATE REQUEST-----`). For S/MIME certificates, if you omit the CSR, you must generate the CSR in the browser after the order is created. For browser-generated certificates, DigiCert uses an RSA algorithm, SHA256 signature hash, and a 2048-bit key length CSR. To get a certificate with a different key length, signature hash, or algorithm, you must include a CSR with your request. Note: The Services API does not extract information from the CSR to fill in the details of a certificate request.
.. is_rsassa_pss	optional	bool	For certificate requests with an RSA CSR or public key, this parameter changes the type of RSA signature DigiCert uses for the end-entity certificate. If `true`, DigiCert issues the end-entity certificate with an RSASSA-PSS signature. If `false` (default), DigiCert issues the end-entity certificate with an RSA signature. Important: This parameter is only honored when the issuing ICA certificate has an RSA key. If the issuing ICA certificate has an ECC key, DigiCert issues the end-entity certificate with an ECC signature that has same key size as the issuing ICA certificate.
.. emails	required	array of strings	List of one or more email addresses to secure. If using an email address as the common name on the certificate (`common_name_indicator` is `email_address`), the common name is the first email address in this array. Note: Orders for Secure Email for Business and Secure Email for Organization certificates cannot include email addresses from public email service providers unless the domains for those email providers are already validated for the organization in your CertCentral account. Learn more: Email address validation.
.. user_principle_name	optional	array of strings	List of user principle names (UPN) to include in the UPN SAN attribute on the issued certificate. Max length: 1 Max characters per item: 255
.. common_name_indicator	conditional	string	Choose the source of the common name value for the certificate. Required for `secure_email_sponsor` and `secure_email_organization` certificates; ignored for `secure_email_mailbox` certificates. Allowed values: Allowed values depend on product type. See Common name value.
.. individual	conditional	object	First and last name or pseudonym of the individual on the certificate. The `individual` object is only used with Secure Email for Business certificates. When you create an order for a Secure Email for Business certificate, if the `common_name_indicator` is `given_name_surname` or `pseudonym`, you must populate the `individual` object in your request body
.. .. first_name	conditional	string	Individual first name. Required if `common_name_indicator` is `given_name_surname`.
.. .. last_name	conditional	string	Individual last name. Required if `common_name_indicator` is `given_name_surname`.
.. .. pseudonym	conditional	string	Individual pseudonym. Required if `common_name_indictator` is `pseudonym`.
.. include_email_in_subject (Deprecated)	optional	boolean	If `true`, the first email address in the `emails` array is included in the subject email field on the issued certificate. Otherwise, `false` (default). Deprecated. Use `subject.include_email`, instead.
.. usage_designation	required	object	Object that determines the primary use and additional uses for the certificate. Learn more: Certificate uses.
.. .. primary_usage	required	string	Primary use for the certificate. Allowed values: See Primary uses.
.. .. additional_usages	optional	array	List of additional certificate uses. Allowed values: See Additional uses.
.. signature_hash	optional	string	Hash algorithm used to signing the certificate. Allowed values:: `sha256` (default), `sha384`, `sha512`
.. ca_cert_id	optional	string	ID of the intermediate certificate authority (ICA) certificate to select as the issuing certificate. To get the `ca_cert_id` value for an ICA, use the Product list endpoint. Account administrators can customize the default and allowed ICAs for each product at the container or user role level. If you do not provide a value for this parameter, we issue the certificate using the default ICA. If you provide the `ca_cert_id` value for an ICA that is not allowed, the request returns an error^. To see the custom ICA settings for each product, use the Product limits endpoint. ^This parameter is ignored if the option for ICA selection is not enabled for your account. Learn more about the ICA certificate chain feature for your public TLS certificates.
auto_renew	optional	integer	Number of times the certificate should renew automatically.
renewal_of_order_id	optional	integer	If order is a renewal, enter the previous order's ID.
skip_approval	optional	boolean	Specify if the order should skip the approval step and be immediately submitted for validation and issued when complete. Default: `false`
organization	conditional	object	Required on orders for Secure Email for Business and Secure Email for Organization certificates. Not used on orders for Secure Email for Mailbox certificates. Object with information about the organization to associate with the request. You can associate the request with an existing organization, or you can create a new organization when you submit the order request. To associate the request with an existing organization, pass the ID of the organization as the value of `organization.id` in the body of your request. To create a new organization, include the details of the organization in the `organization` object. For more information about the structure and required parameters of the `organization` object, see the Create organization documentation. Note: When you submit an order with organization details instead of providing an organization ID, we check the organizations that already exist in your account to avoid creating a duplicate. If we find one matching organization, we automatically associate the order with that organization instead of creating a new one. If we find two or more matching organizations, we automatically associate the order with the oldest matching organization in your account instead of creating a new one. To override this behavior and force the request to create a new organization, set the `organization.skip_duplicate_org_check` parameter to `true` in the body of your request. Important: When you want to associate an order with an existing organization, we recommend always using the ID of the organization instead of the organization's details in the body of your request. To get the ID values for organizations in your account, use the List organizations endpoint. Additionally, we recommend deactivating unused organizations to ensure they are never accidentally assigned to a new order request. To deactivate an organization, use the Deactivate organization endpoint.
.. id	conditional	integer	The ID of an existing organization to associate with the order. To get the ID of organizations in your account, use the List organizations endpoint. Required if you are using an existing organization on the order.
.. contacts	conditional	array of objects	List of contacts for the organization. When creating a new organization: Providing an `organization_contact` is optional. If omitted, the organization is created and the authenticated user is saved as the organization contact. Providing a `technical_contact` is optional. If omitted, the organization is created with no technical contact. When using an existing organization ID: Providing an `organization_contact` and `technical_contact` is optional. If provided, the new organization and technical contact replace the existing contacts stored on the organization.
.. skip_duplicate_org_check	optional	boolean	Use `true` to skip the check for duplicate organizations in your account. When you skip this check, you force the request to create a new organization, regardless of whether the details you provide in the request match the details of an organization that already exists in your account. Default: `false`
container	optional	object	If needed, specify the container the order should be placed under.
.. id	optional	integer	Container ID.
order_validity	required	object	Defines the validity period of the certificate and order.
.. years	conditional	integer	Number of years the certificate and order are valid. Can be replaced by `order_validity.days` or `order_validity.custom_expiration_date`. Range: `1`-`3`
.. days	conditional	integer	Number of days the certificate and order are valid. Overrides `order_validity.years`.
.. custom_expiration_date	conditional	string	Custom expiration date for the certificate and order. Overrides `order_validity.days` and `order_validity.years`. Format: `dd MMM YYYY` (for example, `"09 JUN 2025"`)
custom_fields	conditional	object	Account-specific custom fields. Whether or not these fields are required depends on your custom field settings.
.. metadata_id	required	integer	Custom field ID.
.. value	required	string	Value for the custom field. Data validation type depends on your custom field settings.
payment_method	optional	string	Payment method for the order. Allowed values: `balance` (default): Pay with account balance. Returns an error if the option to bill to account balance is disabled for the account, or if the account balance has insufficient funds. Learn how to debit purchases against your CertCentral account balance. `profile`: Pay with the account’s default credit card. Returns an error if no default credit card is configured for the account. Learn how to set up a default credit card. `card`: Pay with a new credit card. Requests that use `card` as the payment method must include a `credit_card` and `billing_address` object. Returns an error if the option to pay with a credit card is disabled for the account.
credit_card	conditional	object	Object with information about the credit card charged for the order. Required if `payment_method` is `card`.
.. number	required	string	Credit card number.
.. expiration_month	required	integer	Credit card expiration month. Format as a two-digit number between `01` (Jan) and `12` (Dec).
.. expiration_year	required	integer	Credit card expiration year. Format as a four-digit number. For example: `2026`
.. cvv	required	integer	Card verification value (CVV). Format as a three- or four-digit number. For example: `333` or `4444`
.. cardholder_name	required	string	Cardholder’s first and last name.
billing_address	conditional	object	Object with information about the billing address. Required if `payment_method` is `card`.
.. address	required	string	Billing street address.
.. address2	optional	string	Continuation of street address.
.. city	required	string	Billing city.
.. state	conditional	string	Billing state or province. Optional for some countries.
.. country	required	string	Billing country.
.. zip	conditional	string	Billing zip or postal code. Optional for some countries.
vat_number	optional	string	If the payment method is `card` (new credit card) or `profile` (default credit card), use the `vat_number` request parameter to set a value-added tax (VAT) or goods and services tax (GST) identification number for the order transaction. DigiCert includes this number on the transaction receipt as a reference for your financial records. If omitted, DigiCert uses the VAT/GST number from the finance settings for the CertCentral account. If the VAT/GST number is absent from both the order request and account settings, DigiCert doesn't store a VAT/GST number for the transaction. Note DigiCert only stores a VAT/GST number for credit card transactions. For orders using other payment methods, the `vat_number` request parameter is ignored. VAT/GST numbers are not supported for DigiCert USA and DigiCert Japan billing entities. If the billing entity for the account is DigiCert, Inc. (US) or DigiCert Japan G.K. (Japan), the `vat_number` parameter is ignored, and DigiCert doesn't store a VAT/GST number for the transaction. To learn more about your account's billing entity, contact your account manager.
alternative_order_id	optional	string	A custom alphanumeric ID to assign the order. To see the `alternative_order_id` assigned to an order, use the Order info endpoint. Alternative order IDs do not replace the unique order ID that DigiCert assigns each order request. You cannot use alternative order IDs to search for or identify orders in API calls that require an `order_id` parameter in the URL path or request body. If the Require unique alternative order IDs option is enabled in your account settings, you cannot submit order requests with an alternative order ID that is already assigned to an order in your account. Use this feature to enable nonce order requests, or to prevent your integration from creating duplicate orders in cases where you do not receive a response from the API. Account administrators can toggle this option from the CertCentral console. From the Settings > Preferences page, open the Advanced Settings menu, and look for the Alternative order ID option. This parameter is always optional, even if the Require unique alternative order IDs option is enabled in your account. If a request does not use this parameter, no `alternative_order_id` value is assigned to the order. Maximum length: 64 characters Note: The Require unique alternative order IDs option may not appear in the advanced settings menu for all CertCentral accounts. To enable this option for your account, contact your account manager or our Support team.
enable_guest_access	optional	int	Whether to enable guest access for the order. This parameter is not allowed if guest access is disabled in your account settings. Allowed values:`1` (enabled) or `0` (disabled) Default: The default configuration for new orders is determined by your account settings. Account administrators can change these settings from the Guest Access page in the CertCentral console.
reject_if_pending	optional	bool	If `true`, CertCentral rejects the request when DigiCert cannot immediately issue the certificate. Instead of creating a pending order, the API returns an HTTP response status code of `400 Bad Request`, with the error code `order_failed_to_immediately_issue`. If `false` (default), when DigiCert cannot immediately issue the certificate, CertCentral creates a pending order. The API returns an HTTP response status code of `200 OK`, and the response contains the `id` of the pending order.
subject	optional	object	Object with optional data to include in subject distinguished name (DN) attributes on the issued certificate.
.. serial_number	optional	string	Value to use in the subject DN serial number attribute. Supported on `secure_email_sponsor` certificates. Character limit: 100
.. pseudonym	optional	string	Value to use in the subject DN pseudonym attribute. Supported on `secure_email_sponsor` certificates. Note: If you are already submitting the `pseudonym` value in the `certificate.individual` object, use `subject.include_pseudonym` instead. Character limit: 128
.. job_title	optional	string	Value to use in the subject DN title attribute. Supported on `secure_email_sponsor` certificates. Character limit: 128
.. include_pseudonym	optional	boolean	If `true`, the subject DN pseudonym attribute includes the `pseudonym` value from the `certificate.individual` object. If `false` (default), the subject DN does not include the pseudonym attribute. Note: If there is no `pseudonym` value on the `certificate.individual` object, set the value of the subject DN pseudonym attribute with `subject.pseudonym`, instead.
.. include_email	optional	boolean	If `true`, the subject DN email attribute includes the first email address from the `certificate.emails` array. Otherwise, `false` (default). Supported on `secure_email_individual`, `secure_email_sponsor`, and `secure_email_organization` certificates.
.. include_given_name_surname	optinal	boolean	If `true`, the subject DN surname and given name attributes include surname and given name from the `individual` array. Otherwise, `false` (default). Supported on `secure_email_sponsor` certificates.

Response parameters

Name	Type	Description
id	int	Order ID.
requests	array of objects	Contains information about the request. Not returned if the order skipped the request approval step.
.. id	int	Request ID.
.. status	string	Request status. Possible values:`pending`, `submitted`, `approved`, `rejected`
certificate_id	int	Certificate ID. Returned if the order skipped the request approval step, or if the request was automatically approved (request status is `approved`).

In this section:

Order Secure Email (S/MIME) certificate

Example requests and responses

Certificate uses

Note

Primary uses

Additional uses

RSA CSR

ECC CSR

Important

Note

Common name value

Note

Warning

Optional subject DN attributes

Optional subject alternative name (SAN) attributes

Note

Email address validation

Secure Email for Individual

Secure Email for Business and Secure Email for Organization

Note

Request parameters

Response parameters

Search results