CreateDomainIdentity method
This method creates an address in a folder. The folder is selected based on the service account the request originates from.
When creating an address, you can set up the DKIM signature in one of these two ways:
- Simple (Easy DKIM): Yandex Cloud Postbox generates and stores DKIM keys all by itself. Used by default if the
DkimSigningAttributesobject is not provided or has only theNextSigningKeyLengthfield specified. In the response, the service returns selectors (Tokens) based on which you need to add CNAME records to the DNS of the user domain. - Advanced (BYODKIM): A key is provided by the user. This method can be used only if both fields,
DomainSigningSelectorandDomainSigningPrivateKey, are provided in theDkimSigningAttributesobject.
Request
POST /v2/email/identities HTTP/2
Request headers
Use common request headers in your requests.
Request body
{
"EmailIdentity": "<address>",
"Tags": [
{
"Key": "<label_key>",
"Value": "<label_value>"
}
],
"DkimSigningAttributes": {
"NextSigningKeyLength": "<key_length>",
"DomainSigningSelector": "<selector_name>",
"DomainSigningPrivateKey": "<private_key>"
},
"ConfigurationSetName": "<configuration_name>"
}
|
Parameter |
Description |
|
|
Type: String. Address. |
|
|
Type: Array. Address label array. The maximum number of labels is 50. |
|
|
Type: String. Label key. The keyword may be from 1 to 63 characters long. |
|
|
Type: String. Label value. It may be from 0 (no value) to 256 characters long. |
|
|
Type: Object. Optional object containing the DKIM signature parameters. The DKIM configuration method is determined by the object's contents:
If the object is not provided, the simple DKIM setting with a 2048-bit RSA key is used. The request will fail if you provide only one of the two fields ( |
|
|
Type: String. This is an optional field. Length of the RSA key Yandex Cloud Postbox will generate when setting up Easy DKIM. The possible values are:
You cannot provide this field together with the |
|
|
Type: String. Name of the selector used to identify the public key in the domain’s DNS configuration. The selector name may be from 1 to 63 characters long. |
|
|
Type: String. Private key used to generate a DKIM signature. The private key must use 1,024-bit or 2,048-bit RSA encryption and base64 encoding. It may be from 1 to 20,480 characters long. |
|
|
Type: String. Name of the configuration you want to link to the address. The configuration must reside in the same folder as the address. |
Responses
200 OK
{
"IdentityType": "<address_type>",
"VerifiedForSendingStatus": <verification_status_for_sending_emails>,
"DkimAttributes": {
"SigningEnabled": <use_DKIM>,
"Status": "<DKIM_search_status>",
"Tokens": [
"<public_key_selector>"
],
"SigningAttributesOrigin": "<DKIM_configuration_method>",
"NextSigningKeyLength": "<next_key_length>",
"CurrentSigningKeyLength": "<current_key_length>"
}
}
|
Parameter |
Description |
|
|
Type: String. Address type. The possible value is |
|
|
Type: Boolean. Indicates whether address ownership is verified. The possible values are You can send emails only from verified addresses. |
|
|
Type: Object. Object that contains the DKIM signature parameters. |
|
|
Type: Boolean. Indicates whether a DKIM signature is used when sending from this address. The possible values are |
|
|
Type: String. Indicates whether Yandex Cloud Postbox was able to detect a DKIM signature in the DNS configuration of the address. The possible values are:
|
|
|
Type: Array. List of selectors for public key identification. The Easy DKIM setup returns two selectors: for each one, you need to add a CNAME record to the DNS of the user domain to verify domain ownership. Selector type: String. |
|
|
Type: String. Indicates how the DKIM signature was configured. The possible values are:
|
|
|
Type: String. Length of the RSA key that will be used for the next DKIM key rotation when using Easy DKIM. It can be either |
|
|
Type: String. Length of the current RSA key used for DKIM signing when using Easy DKIM. It can be either |
The 200 OK response may contain additional parameters. Its format may vary slightly from the above.
Errors
For all errors, the response body has the same format:
{
"Code": "<error_name>",
"message": "<error_description>"
}
The name of the error is taken from its code, e.g., BadRequestException.
The possible errors include:
|
Error code |
Description |
|
|
The request contains invalid headers or parameters. |
|
|
The requested resource was not found. |
|
|
A configuration with this name already exists. Specify a different name. |
|
|
There are conflicting operations. Wait for the previous operation to complete and repeat your request. |
|
|
The request quota was exceeded. |
|
|
The request limit was exceeded. |