HomeGuidesAPI ReferenceRecipesChangelogStatus
Guides
Help CenterMy API Keys 🔑

Fetch all your weekly transactional events

Suggest Edits

💡

This is an exclusive Brevo+ feature.

If you happen to have a high volume of transactional events on a weekly basis this service will allow you to generate raw data exports of all the generated webhook calls on a 7 day time period. Usually you should be able to easily pipe out the exported data into further analytics tools.

The way the service works is by declaring a webhook on your infrastructure which will receive a link to a CSV file containing the unaggregated raw-data once the export is computed. If the raw data volumes are to high you will receive a compressed file with multiple CSVs in it.

Currently the data exports include the following events:

📘

Mapping of Events

Reference: Get personalized content of a sent Transactional email

The equivalences of event names in the guides vs API responses are as follows:
'sent': 'requests',
'delivered': 'delivered',
'hard_bounce': 'hardBounces',
'soft_bounce': 'softBounces',
'click': 'clicks',
'open': 'opened',
'spam': 'spam',
'blocked': 'blocked',
'invalid': 'invalid',
'unsubscribe': 'unsubscribed',
'deferred': 'deferred',
'error': 'error',
'proxy_open': 'loadedByProxy',
'invalid_email': 'invalid'


Define an export notify url

First you will need to create a notify URL on your side which will receive the webhook call containing the information and path of the generated CSV file with your transactional raw data. Keep in mind that the persistence of the data is of 7 days.

Example 

curl --request POST \
     --url https://mydomain.com/importData \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     
     ------
     ==> Returns 'success' to our servers

Post a new job export

In order to execute the export job you will need to call the following endpoint:

  • Export all transactional events
    Note for this example we will create a job request for allEvents registered in the past 7 days. You can also define more specific queries based on additional filters. 
curl --request POST \
     --url https://api.brevo.com/v3/webhooks/export \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "event": "allEvents",
  "type": "transactional",
  "days": 7
}
'

Response

If your request is successfully accepted you will receive in exchange a processId which you can use to further track the status of your asynchronous operation via the following endpoint:

{
  "processId": 1843555083931176858
}

Receiving the raw data on your application

Once the asynchronous job has been completed your notifyURL will receive the following payload indicating the data is ready and uploaded to the url path as shown below. Note that there's a path expiry time for each data export, so ideally you should download the contents of the file before it is removed from our servers. 

{
  "url": "https://webhooks-export.brevo.com/webhook-export-2036548-1680071958.zip?Expires=1680075559&KeyName=webhooks-export-cdn&Signature=sop8E-xYkUd8keGKb60CcIaPp0c=",
  "process_id": 1843555083931176858
}

CSV contents

date,email,event,id,message-id,reason,sending_ip,subject,tag,tags,template_id,ts,ts_epoch,ts_event,X-Mailin-custom,link,s_returnpath
2023-03-15 11:09:22 +0000 UTC,[email protected],spam,13997,<[email protected]>,sent,127.0.0.1,Test Subject,,"[""testTag1"",""testTag2"",""testTag3"",""testTag4""]",45678,1676545042,1676534500,1676545042,TEST-X-Mailin-custom,https://brevo.com,false
2023-03-15 11:09:22 +0000 UTC,[email protected],spam,13997,<[email protected]>,sent,127.0.0.1,Test Subject,,"[""testTag1"",""testTag2"",""testTag3"",""testTag4""]",45678,1676545042,1676534500,1676545042,TEST-X-Mailin-custom,https://brevo.com,false
2023-03-15 11:09:22 +0000 UTC,[email protected],spam,13997,<[email protected]>,sent,127.0.0.1,Test Subject,,"[""testTag1"",""testTag2"",""testTag3"",""testTag4""]",45678,1676545042,1676534500,1676545042,TEST-X-Mailin-custom,https://brevo.com,false
2023-03-15 11:09:22 +0000 UTC,[email protected],spam,13997,<[email protected]>,sent,127.0.0.1,Test Subject,,"[""testTag1"",""testTag2"",""testTag3"",""testTag4""]",45678,1676545042,1676534500,1676545042,TEST-X-Mailin-custom,https://brevo.com,false
2023-03-15 11:09:22 +0000 UTC,[email protected],spam,13997,<[email protected]>,sent,127.0.0.1,Test Subject,,"[""testTag1"",""testTag2"",""testTag3"",""testTag4""]",45678,1676545042,1676534500,1676545042,TEST-X-Mailin-custom,https://brevo.com,false

Checking the status of an ongoing export job

Query the process_id you received as response on the Return the informations for a process endpoint. 

{
  "id": 1843555083931176858,
  "status": "completed",
  "name": "EXPORT_TRANSACTIONAL",
  "export_url": "https://webhooks-export.brevo.com/webhook-export-2036548-1680071958.zip?Expires=1680075559&KeyName=webhooks-export-cdn&Signature=sop8E-xYkUd8keGKb60CcIaPp0c="
}

📘

Limitations and quotas

  • Whenever you start using this feature bear in mind the maximum exports you can generate on a 7 day basis is of 20 executions.
  • If the data volume is too high you will receive a compressed file with multiple CSV files in it which you will need to iterate on and upload to your system.

Updated about 1 month ago