Domain creation and management

Domains authenticate and verify senders so recipients know the email comes from a genuine source. For endpoints to create and manage domains, see API reference > Domains.

1. Creating a new domain

Send a POST request to https://api.brevo.com/v3/senders/domains to create a new domain. Use the cURL request below:

1 curl --request POST \
2      --url https://api.brevo.com/v3/senders/domains \
3      --header 'accept: application/json' \
4      --header 'api-key:' \
5      --header 'content-type: application/json' \
6      --data '
7 {
8   "name": "mycompany.com"
9 }
10 '

Add your API key in the api-key header. This endpoint has one body parameter:

Attribute	Datatype	Description	Value
`name`	String	Name of the domain being created.	mydomain.com

Response

Sample success response:

1 {
2   "id": "641db448a6a7ea326e585e15",
3   "domain_name": "mycompany.com",
4   "message": "Domain added successfully. To authenticate it, add following DNS records",
5   "dns_records": {
6     "dkim_record": {
7       "type": "TXT",
8       "value": "k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDeMVIzrCa3T14JsNY0IRv5/2V1/v2itlviLQBwXsa7shBD6TrBkswsFUToPyMRWC9tbR/5ey0nRBH0ZVxp+lsmTxid2Y2z+FApQ6ra2VsXfbJP3HE6wAO0YTVEJt1TmeczhEd2Jiz/fcabIISgXEdSpTYJhb0ct0VJRxcg4c8c7wIDAQAB",
9       "host_name": "mail._domainkey.",
10       "status": false
11     },
12     "brevo_code": {
13       "type": "TXT",
14       "value": "brevo-code:4bc1566441c4131069853d135c5905ab",
15       "host_name": "",
16       "status": false
17     }
18   }
19 }

Sample bad request response:

1 {
2   "code": "invalid_parameter",
3   "message": "Enter domain name in correct format. Example: myexampledomain.com"
4 }

Response codes:

Response code	Message	Description
`200`	Domain created	Returned when a domain is created.
`400`	Bad request	Returned when invalid or missing parameters are sent.

2. Getting the list of your domains

Send a GET request to https://api.brevo.com/v3/senders/domains to retrieve the domains you’ve created. Use the cURL request below:

1 curl --request GET \
2      --url https://api.brevo.com/v3/senders/domains \
3      --header 'accept: application/json' \
4      --header 'api-key: '

No attributes for getting the list of your domains

This endpoint takes no parameters. The request uses your API key to retrieve and return the domains you’ve created.

Response

The response returns all the domains you’ve created. Sample JSON:

1 {
2   "domains": [
3     {
4       "id": "641db6b43f10ae7b6604d178",
5       "domain_name": "mycompany.com",
6       "authenticated": false,
7       "verified": false,
8       "validationRequest": null,
9       "verifier": null,
10       "authenticator": null,
11       "creator": {
12         "id": "63930fe975f3bf52825956b7",
13         "email": "obaidullah.khan@brevo.com",
14         "method": null,
15         "creationDate": "2023-03-24T14:41:56+00:00"
16       },
17       "ip": null
18     }
19   ],
20   "count": 1,
21   "current_page": 1,
22   "total_pages": 1
23 }

Response codes:

Response code	Message	Description
`200`	List of domains	Returns the list of domains.
`400`	Bad request	Returned for incorrect parameters or an invalid API key.

3. Delete a domain

Send a DELETE request to https://api.brevo.com/v3/senders/domains/{domainName} to delete a domain. Insert the domain name in the endpoint URL as shown below:

1 curl --request DELETE \
2      --url https://api.brevo.com/v3/senders/domains/mydomain.com \
3      --header 'accept: application/json' \
4      --header 'api-key: '

A null response indicates the domain was deleted. This endpoint takes only the domainName attribute:

Attribute	Datatype	Description	Value
`domainName`	String	Name of the domain	mycompany.com

Response

Response code	Message	Description
`200`	Domain deleted	Domain deleted.
`400`	Bad request	Invalid, incorrect, or missing parameters.
`404`	Domain does not exist	Domain does not exist in the database.

1	curl --request POST \
2	--url https://api.brevo.com/v3/senders/domains \
3	--header 'accept: application/json' \
4	--header 'api-key:' \
5	--header 'content-type: application/json' \
6	--data '
7	{
8	"name": "mycompany.com"
9	}
10	'

1	{
2	"id": "641db448a6a7ea326e585e15",
3	"domain_name": "mycompany.com",
4	"message": "Domain added successfully. To authenticate it, add following DNS records",
5	"dns_records": {
6	"dkim_record": {
7	"type": "TXT",
8	"value": "k=rsa;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDeMVIzrCa3T14JsNY0IRv5/2V1/v2itlviLQBwXsa7shBD6TrBkswsFUToPyMRWC9tbR/5ey0nRBH0ZVxp+lsmTxid2Y2z+FApQ6ra2VsXfbJP3HE6wAO0YTVEJt1TmeczhEd2Jiz/fcabIISgXEdSpTYJhb0ct0VJRxcg4c8c7wIDAQAB",
9	"host_name": "mail._domainkey.",
10	"status": false
11	},
12	"brevo_code": {
13	"type": "TXT",
14	"value": "brevo-code:4bc1566441c4131069853d135c5905ab",
15	"host_name": "",
16	"status": false
17	}
18	}
19	}

1	{
2	"code": "invalid_parameter",
3	"message": "Enter domain name in correct format. Example: myexampledomain.com"
4	}

1	curl --request GET \
2	--url https://api.brevo.com/v3/senders/domains \
3	--header 'accept: application/json' \
4	--header 'api-key: '

1	{
2	"domains": [
3	{
4	"id": "641db6b43f10ae7b6604d178",
5	"domain_name": "mycompany.com",
6	"authenticated": false,
7	"verified": false,
8	"validationRequest": null,
9	"verifier": null,
10	"authenticator": null,
11	"creator": {
12	"id": "63930fe975f3bf52825956b7",
13	"email": "obaidullah.khan@brevo.com",
14	"method": null,
15	"creationDate": "2023-03-24T14:41:56+00:00"
16	},
17	"ip": null
18	}
19	],
20	"count": 1,
21	"current_page": 1,
22	"total_pages": 1
23	}

1	curl --request DELETE \
2	--url https://api.brevo.com/v3/senders/domains/mydomain.com \
3	--header 'accept: application/json' \
4	--header 'api-key: '