External feeds management

This document describes the public API reference for the External feed endpoints.

Cache behavior: When caching is enabled (cache: true), external feed data is cached using a time-based TTL of 1 hour. The cache does not expire based on the number of emails sent. After any feed change (create, update, or delete), the stale cache may persist for up to 1 hour before the new data is served.

1. Fetch all external feeds

Send a GET request to https://api.brevo.com/v3/feeds to retrieve all your external feeds. Use the cURL request below:

1 curl --request GET \
2      --url 'https://api.brevo.com/v3/feeds?search=search&startDate=2022-09-04&endDate=2022-10-01&sort=desc&authType=basic&limit=50&offset=0' \
3      --header 'accept: application/json' \
4      --header 'api-key: '

The attributes used in the cURL request are defined below.

Attributes	Datatype	Description	Value
`search`	String	Can be used to filter records by search keyword on feed name	search
`startDate`	Date	Mandatory if endDate is used. Starting date (YYYY-MM-DD) from which you want to fetch the list. Can be maximum 30 days older than current date.	2022-09-04
`endDate`	Date	Mandatory if startDate is used. Ending date (YYYY-MM-DD) till which you want to fetch the list. Maximum time period that can be selected is one month.	2022-10-01
`sort`	String	Sort the results in the ascending/descending order of record creation. Default order is descending if sort is not passed.	desc
`authType`	String	Filter the records by authType of the feed. (Has multiple authentication types)	basic
`limit`	Int64	Number of documents returned per page.	50
`offset`	Int64	Index of the first document on the page.	0

Response

A sample JSON response:

1 {
2   "count": 3,
3   "feeds": [
4     {
5       "id": "d955aaa4-f4d6-4557-aa14-24286542ed8d",
6       "name": "api feed token",
7       "url": "https://abc.com/",
8       "authType": "token",
9       "token": "jfhdkjdfhjkfdhjkdfhjkdfhkj",
10       "headers": [
11         {
12           "name": "key",
13           "value": "val"
14         }
15       ],
16       "maxRetries": 4,
17       "cache": true,
18       "createdAt": "2022-10-06T05:03:47.053000000Z",
19       "modifiedAt": "2022-10-06T05:03:47.053000000Z"
20     },
21     {
22       "id": "311a71ac-bebc-42cf-963d-d8666dfe53e9",
23       "name": "api feed basic",
24       "url": "https://abc.com/",
25       "authType": "basic",
26       "username": "user",
27       "password": "pass",
28       "headers": null,
29       "maxRetries": 2,
30       "cache": false,
31       "createdAt": "2022-10-06T04:48:19.767000000Z",
32       "modifiedAt": "2022-10-06T04:48:19.767000000Z"
33     }
34   ]
35 }

Response codes:

Response code	Message	Description
`200`	External feeds	Returns the external feed details.
`400`	Invalid parameters passed	Returned when invalid or out-of-range parameters are passed.
`404`	Record not found	Returned when results or records are not found. This may occur due to an incorrect request.

2. Create an external feed

Send a POST request to https://api.brevo.com/v3/feeds to create an external feed. Use the cURL request below:

1 curl --request POST \
2      --url https://api.brevo.com/v3/feeds \
3      --header 'accept: application/json' \
4      --header 'api-key: ' \
5      --header 'content-type: application/json' \
6      --data '
7 {
8   "authType": "basic",
9   "headers": [
10     {
11       "name": "userId",
12       "value": "user12345"
13     }
14   ],
15   "maxRetries": 5,
16   "cache": false,
17   "name": "New feed",
18   "url": "https://webhook.site/173lyyx1",
19   "username": "user",
20   "password": "password",
21   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
22 }
23 '

The values and attributes to create a feed:

Attribute	Datatype	Description	Value
`name`	String	Name of the feed	New feed
`url`	Url	URL of the feed	https://webhook.site/173lyyx1
`authType`	String	Auth type of the feed: basic, token or noAuth	basic
`username`	String	Username for authType	user
`password`	String	Password for authType	password
`token`	String	Token for authType	”Random string of letters and number”
`headers`	Array of objects	An array of objects which provide custom headers for the feed	it has objects name and value
`maxRetries`	integer	Maximum number of retries on the feed url	5
`cache`	boolean	Toggle caching of feed url response. When enabled, feed data is cached for 1 hour (time-based TTL). The cache does not expire based on the number of emails sent.	false

Since headers is an array of objects, it has two attributes — name and value:

Object	Datatype	Description	Value
`name`	String	Name of the header	userId
`value`	String	Value of the header	user12345

Response

The API returns the unique id of the feed. Sample response:

1 {
2   "id": "23befbae-1505-47a8-bd27-e30ef739f32c"
3 }

Response codes:

Response code	Message	Description
`201`	Successfully created	External feed created. The response includes the feed `id`.
`400`	Bad request	Request fails due to invalid or missing parameters, or an incorrect request format.

3. Get an external feed by UUID

Send a GET request to https://api.brevo.com/v3/feeds/{uuid}. Use the cURL request below:

1 curl --request GET \
2      --url https://api.brevo.com/v3/feeds/38f351fb-6e77-4b38-979a-a2465260449e \
3      --header 'accept: application/json' \
4      --header 'api-key: '

The only attribute is uuid, the universal identifier for the external feed:

Attribute	Datatype	Description	Value
`uuid`	String	UUID of the feed to fetch	38f351fb-6e77-4b38-979a-a2465260449e

Response

1 {
2   "id": "d955aaa4-f4d6-4557-aa14-24286542ed8d",
3   "name": "api feed token",
4   "url": "https://abc.com/",
5   "authType": "token",
6   "token": "jfhdkjdfhjkfdhjkdfhjkdfhkj",
7   "headers": [
8     {
9       "name": "key",
10       "value": "val"
11     }
12   ],
13   "maxRetries": 4,
14   "cache": true,
15   "createdAt": "2022-10-06T05:03:47.053000000Z",
16   "modifiedAt": "2022-10-06T05:03:47.053000000Z"
17 }

Response code	Message	Description
`200`	External feeds	Returns the external feed details.
`400`	Bad request	Returned when invalid or out-of-range parameters are passed.
`404`	Feed not found	Returned when results or feeds are not found. This may occur due to an incorrect request.

4. Update an external feed

Send a PUT request to https://api.brevo.com/v3/feeds/{uuid} to update an external feed. Use the cURL request below:

1 curl --request PUT \
2      --url https://api.brevo.com/v3/feeds/38f351fb-6e77-4b38-979a-a2465260449e \
3      --header 'accept: application/json' \
4      --header 'content-type: application/json' \
5      --data '
6 {
7   "headers": [
8     {
9       "name": "userId",
10       "value": "user12345"
11     }
12   ],
13   "maxRetries": 5,
14   "cache": false,
15   "name": "New feed",
16   "url": "https://webhook.site/173lyyx1",
17   "authType": "token",
18   "username": "user",
19   "password": "password",
20   "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
21 }
22 '

Two parameter groups apply: path params and body params.

Path params

Attribute	Datatype	Description	Value
`uuid`	String	UUID of the feed to update	38f351fb-6e77-4b38-979a-a2465260449e

Body params

Attribute	Datatype	Description	Value
`name`	String	Name of the feed	New feed
`url`	Url	Url of the feed	https://webhook.site/173lyyx1
`authType`	String	Auth type of the feed: basic, token, noAuth	token
`username`	String	Username for authType basic	user
`password`	String	Password for authType basic	password
`token`	String	Token for authType token	Random numbers and letters
`headers`	Array of objects	Custom headers for the feed	Contains objects name and value
`maxRetries`	Integer	Maximum number of retries on the feed url	5
`cache`	Boolean	Toggle caching of feed url response. When enabled, feed data is cached for 1 hour (time-based TTL). After updating a feed, the stale cache may persist for up to 1 hour before the new data is served.	false

Since headers is an array of objects, it contains two attributes:

Object	Datatype	Description	Value
`name`	String	Name of header	userId
`value`	String	Value of header	user12345

Response

A 204 response with no message indicates the external feed was updated. Response codes:

Response code	Message	Description
`204`	Feed updated	Feed was updated.
`400`	Bad request	Request fails due to invalid parameters.
`404`	Feed not found	Returned when the feed cannot be found, often due to incorrect parameters or UUID.

5. Delete an external feed

Send a DELETE request to https://api.brevo.com/v3/feeds/{uuid} to delete a feed. Use the cURL request below:

1 curl --request DELETE \
2      --url https://api.brevo.com/v3/feeds/38f351fb-6e77-4b38-979a-a2465260449e \
3      --header 'accept: application/json' \
4      --header 'api-key: '

The only attribute is uuid:

Attribute	Datatype	Description	Value
`uuid`	String	UUID of the feed to fetch	38f351fb-6e77-4b38-979a-a2465260449e

Response

An empty body with response code 200 indicates the feed was deleted.

Response codes:

Response code	Message	Description
`200`	Feed deleted	Feed was deleted successfully.
`400`	Bad request	Returned when invalid or missing parameters are sent.
`404`	Feed not found	Returned when no feed matches the request.

1	curl --request GET \
2	--url 'https://api.brevo.com/v3/feeds?search=search&startDate=2022-09-04&endDate=2022-10-01&sort=desc&authType=basic&limit=50&offset=0' \
3	--header 'accept: application/json' \
4	--header 'api-key: '

1	{
2	"count": 3,
3	"feeds": [
4	{
5	"id": "d955aaa4-f4d6-4557-aa14-24286542ed8d",
6	"name": "api feed token",
7	"url": "https://abc.com/",
8	"authType": "token",
9	"token": "jfhdkjdfhjkfdhjkdfhjkdfhkj",
10	"headers": [
11	{
12	"name": "key",
13	"value": "val"
14	}
15	],
16	"maxRetries": 4,
17	"cache": true,
18	"createdAt": "2022-10-06T05:03:47.053000000Z",
19	"modifiedAt": "2022-10-06T05:03:47.053000000Z"
20	},
21	{
22	"id": "311a71ac-bebc-42cf-963d-d8666dfe53e9",
23	"name": "api feed basic",
24	"url": "https://abc.com/",
25	"authType": "basic",
26	"username": "user",
27	"password": "pass",
28	"headers": null,
29	"maxRetries": 2,
30	"cache": false,
31	"createdAt": "2022-10-06T04:48:19.767000000Z",
32	"modifiedAt": "2022-10-06T04:48:19.767000000Z"
33	}
34	]
35	}

1	curl --request POST \
2	--url https://api.brevo.com/v3/feeds \
3	--header 'accept: application/json' \
4	--header 'api-key: ' \
5	--header 'content-type: application/json' \
6	--data '
7	{
8	"authType": "basic",
9	"headers": [
10	{
11	"name": "userId",
12	"value": "user12345"
13	}
14	],
15	"maxRetries": 5,
16	"cache": false,
17	"name": "New feed",
18	"url": "https://webhook.site/173lyyx1",
19	"username": "user",
20	"password": "password",
21	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
22	}
23	'

1	curl --request GET \
2	--url https://api.brevo.com/v3/feeds/38f351fb-6e77-4b38-979a-a2465260449e \
3	--header 'accept: application/json' \
4	--header 'api-key: '

1	curl --request PUT \
2	--url https://api.brevo.com/v3/feeds/38f351fb-6e77-4b38-979a-a2465260449e \
3	--header 'accept: application/json' \
4	--header 'content-type: application/json' \
5	--data '
6	{
7	"headers": [
8	{
9	"name": "userId",
10	"value": "user12345"
11	}
12	],
13	"maxRetries": 5,
14	"cache": false,
15	"name": "New feed",
16	"url": "https://webhook.site/173lyyx1",
17	"authType": "token",
18	"username": "user",
19	"password": "password",
20	"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
21	}
22	'

1	curl --request DELETE \
2	--url https://api.brevo.com/v3/feeds/38f351fb-6e77-4b38-979a-a2465260449e \
3	--header 'accept: application/json' \
4	--header 'api-key: '