API

This guide is for using the API from the backend. If it is possible to do it from the frontend, we will mention it clearly.

Quick guide

To subscribe a user to a subscriber list, use the following URL pattern:

https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##

Replace the placeholders with your specific information:

##YOUR_SUBSCRIBER_LIST_ID##
##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in a subscriber list:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you only need to replace the ##YOUR_API_KEY##.

Screenshot of the code guide dialog in a subscriber list.

Request Body:

json

{
  "name": "Jon Doe",
  "email": "jon@doe.com"
}

cUrl:

bash

 curl -X POST "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##" -H "Content-Type: application/json" -H "Authorization: Bearer ##YOUR_API_KEY##" -d '{"name": "Jon Doe", "email": "jon@doe.com"}'

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##'

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_APIKEY##'
  },
  body: JSON.stringify({
    name: 'Jon Doe',
    email: 'jon@doe.com'
  })
})

PHP:

php

  $apiKey = "##YOUR_API_KEY##"; // TODO: replace YOUR_APIKEY

  $url = "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##";

  $data = array(
      'name' => 'userName',
      'email' => 'example@gmail.com'
  );

  $options = array(
      'http' => array(
          'header'  => "Content-Type: application/json\r\n" .
                      "Authorization: Bearer $apiKey\r\n",
          'method'  => 'POST',
          'content' => json_encode($data),
      ),
  );

  $context  = stream_context_create($options);
  $response = file_get_contents($url, false, $context);

Security Warning

Since an API key is very sensitive information, never store it in your frontend code. Always use it from your backend.

Update Subscriber

Quick guide

To update a user from a subscriber list, use the following URL pattern:

https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##

Replace the placeholders with your specific information:

##YOUR_SUBSCRIBER_LIST_ID##
##SUBSCRIBER_EMAIL_ADDRESS##
##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in a subscriber list:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you need to replace the ##YOUR_API_KEY## and ##SUBSCRIBER_EMAIL_ADDRESS##.

Screenshot of the code guide dialog in a subscriber list.

Requiest body:

json

{
  "email": "updated_email@gmail.com",
  "name": "updated subscriber name"
}

cUrl:

bash

curl -X PATCH "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##" -H "Content-Type: application/json" -H "Authorization: Bearer ##YOUR_API_KEY##" -d '{"email": "updated_email@gmail.com", "name": "updated subscriber name"}'

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##'

const response = await fetch(url, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_API_KEY##'
  },
  body: JSON.stringify({
    email: "updated_email@gmail.com",
    name: "updated subscriber name"
  })
})

PHP:

php

$apiKey = "##YOUR_API_KEY##";

$url = "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##";

$data = array(
    'email' => 'updated_email@gmail.com'
    'name' => 'updated subscriber name'
);

$options = array(
    "http" => array(
        "header"  => "Content-Type: application/json\r\n" .
                    "Authorization: Bearer $apiKey\r\n",
        "method"  => "PATCH",
        'content' => json_encode($data),
    ),
);

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

Security Warning

Since an API key is very sensitive information, never store it in your frontend code. Always use it from your backend.

Unsubscribe

Quick guide

To unsubscribe a user from a subscriber list, use the following URL pattern:

https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##

Replace the placeholders with your specific information:

##YOUR_SUBSCRIBER_LIST_ID##
##SUBSCRIBER_EMAIL_ADDRESS##
##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in a subscriber list:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you need to replace the ##YOUR_API_KEY## and ##SUBSCRIBER_EMAIL_ADDRESS##.

Screenshot of the code guide dialog in a subscriber list.

Requiest body:

json

{
  "status": "unsubscribed"
}

cUrl:

bash

curl -X PATCH "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##" -H "Content-Type: application/json" -H "Authorization: Bearer ##YOUR_API_KEY##" -d '{"status": "unsubscribed"}'

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##'

const response = await fetch(url, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_API_KEY##'
  },
  body: JSON.stringify({
    status: 'unsubscribed'
  })
})

PHP:

php

$apiKey = "##YOUR_API_KEY##";

$url = "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##";

$data = array(
    'status' => 'unsubscribed'
);

$options = array(
    "http" => array(
        "header"  => "Content-Type: application/json\r\n" .
                    "Authorization: Bearer $apiKey\r\n",
        "method"  => "PATCH",
        'content' => json_encode($data),
    ),
);

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

Security Warning

Since an API key is very sensitive information, never store it in your frontend code. Always use it from your backend.

Activate Subscription

Quick guide

To activate a user from a subscriber list, use the following URL pattern:

https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##

Replace the placeholders with your specific information:

##YOUR_SUBSCRIBER_LIST_ID##
##SUBSCRIBER_EMAIL_ADDRESS##
##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in a subscriber list:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you need to replace the ##YOUR_API_KEY## and ##SUBSCRIBER_EMAIL_ADDRESS##.

Screenshot of the code guide dialog in a subscriber list.

Requiest body:

json

{
  "status": "active"
}

cUrl:

bash

curl -X PATCH "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##" -H "Content-Type: application/json" -H "Authorization: Bearer ##YOUR_API_KEY##" -d '{"status": "active"}'

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##'

const response = await fetch(url, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_API_KEY##'
  },
  body: JSON.stringify({
    status: 'active'
  })
})

PHP:

php

$apiKey = "##YOUR_API_KEY##";

$url = "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##";

$data = array(
    'status' => 'active'
);

$options = array(
    "http" => array(
        "header"  => "Content-Type: application/json\r\n" .
                    "Authorization: Bearer $apiKey\r\n",
        "method"  => "PATCH",
        'content' => json_encode($data),
    ),
);

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

Security Warning

Since an API key is very sensitive information, never store it in your frontend code. Always use it from your backend.

Pause Subscription

Quick guide

To pause a user from a subscriber list, use the following URL pattern:

https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##

Replace the placeholders with your specific information:

##YOUR_SUBSCRIBER_LIST_ID##
##SUBSCRIBER_EMAIL_ADDRESS##
##YOUR_API_KEY##
##PAUSED_UNTIL##

You can find the IDs to replace by clicking on the code guide button in a subscriber list:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you need to replace the ##YOUR_API_KEY##, ##SUBSCRIBER_EMAIL_ADDRESS## and ##PAUSED_UNTIL##.

Screenshot of the code guide dialog in a subscriber list.

Requiest body:

json

{
  "status": "paused",
  "pausedUntil": "##PAUSED_UNTIL##" //TODO replace date (ISO date string format)
}

cUrl:

bash

curl -X PATCH "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##" -H "Content-Type: application/json" -H "Authorization: Bearer ##YOUR_API_KEY##" -d '{"status": "paused", "pausedUntil": "##PAUSED_UNTIL##" }'

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##'

const response = await fetch(url, {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_API_KEY##'
  },
  body: JSON.stringify({
    status: 'paused',
    pausedUntil: '##PAUSED_UNTIL##'
  })
})

PHP:

php

$apiKey = "##YOUR_API_KEY##";

$url = "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##";

$data = array(
    'status' => 'paused',
    'pausedUntil' => '##PAUSED_UNTIL##'
);

$options = array(
    "http" => array(
        "header"  => "Content-Type: application/json\r\n" .
                    "Authorization: Bearer $apiKey\r\n",
        "method"  => "PATCH",
        'content' => json_encode($data),
    ),
);

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

Security Warning

Since an API key is very sensitive information, never store it in your frontend code. Always use it from your backend.

List Subscribers

Quick guide

To list users from a subscriber list, use the following URL pattern:

https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##

Replace the placeholders with your specific information:

##YOUR_SUBSCRIBER_LIST_ID##
##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in a subscriber list:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you need to replace the ##YOUR_API_KEY##.

Screenshot of the code guide dialog in a subscriber list.

Requiest body:

none.

cUrl:

bash

curl -X GET "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##" -H "Content-Type: application/json" -H "Authorization: Bearer ##YOUR_API_KEY##"

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##'

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_API_KEY##'
  }
})

PHP:

php

$apiKey = "##YOUR_API_KEY##";

$url = "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##";

$options = array(
    "http" => array(
        "header"  => "Content-Type: application/json\r\n" .
                    "Authorization: Bearer $apiKey\r\n",
        "method"  => "GET"
    ),
);

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

Security Warning

Since an API key is very sensitive information, never store it in your frontend code. Always use it from your backend.

Get Subscriber

Quick guide

To get user from a subscriber list, use the following URL pattern:

https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##

Replace the placeholders with your specific information:

##YOUR_SUBSCRIBER_LIST_ID##
##SUBSCRIBER_EMAIL_ADDRESS##
##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in a subscriber list:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you need to replace the ##YOUR_API_KEY## and ##SUBSCRIBER_EMAIL_ADDRESS##.

Screenshot of the code guide dialog in a subscriber list.

Requiest body:

none.

cUrl:

bash

curl -X GET "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##" -H "Content-Type: application/json" -H "Authorization: Bearer ##YOUR_API_KEY##"

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##'

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_API_KEY##'
  }
})

PHP:

php

$apiKey = "##YOUR_API_KEY##";

$url = "https://api.bluefox.email/v1/subscriber-lists/##YOUR_SUBSCRIBER_LIST_ID##/##SUBSCRIBER_EMAIL_ADDRESS##";

$options = array(
    "http" => array(
        "header"  => "Content-Type: application/json\r\n" .
                    "Authorization: Bearer $apiKey\r\n",
        "method"  => "GET"
    ),
);

$context  = stream_context_create($options);
$response = file_get_contents($url, false, $context);

Security Warning

Since an API key is very sensitive information, never store it in your frontend code. Always use it from your backend.

Send transactional email

Quick quide

To send a transactional email, use the following URL pattern:

https://api.bluefox.email/v1/send-transactional

Replace the placeholders with your specific information:

##EMAIL_ID##
##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button on a transactional email card:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you need to replace the ##YOUR_API_KEY##.

Screenshot of a code guide dialog of a transactional email

Request body:

json

{
  "email": "jon@doe.com",
  "transactionalId": "##EMAIL_ID##",
  "data": {
    "example": "example merge tag value"
  },
  "attachments": [] //optional
}

You can include personalization data (merge tags) in the data object. These tags are processed by Handlebars when sent.

cUrl:

bash

curl -X POST \
"https://api.bluefox.email/v1/send-transactional" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ##YOUR_API_KEY##" \
-d '{
  "email": "jon@doe.com", // TODO change email address
  "transactionalId": "##EMAIL_ID##",
  "data": {
    // TODO add the merge tags values
  }
}'

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/send-transactional'
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_API_KEY##' // TODO change YOUR_APIKEY
  },
  body: JSON.stringify({
    email: 'jon@doe.com', // TODO change email address
    transactionalId: '##EMAIL_ID##',
    data: {
    // TODO add the merge tags values
    }
  })
})

PHP:

php

$apiKey = "##YOUR_API_KEY##";

$url = "https://api.bluefox.email/v1/send-transactional";

$email = "example@gmail.com"; // TODO change email address
$transactionalId = "##EMAIL_ID##";
$data = [
  // TODO add the merge tags values
];

$payload = json_encode([
  "email" => $email,
  "transactionalId" => $transactionalId,
  "data" => $data
]);

$options = [
  "http" => [
    "header"  => [
      "Content-Type: application/json",
      "Authorization: Bearer $apiKey"
    ],
    "method"  => "POST",
    "content" => $payload,
  ],
];

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);

Send triggered email

Quick quide

To send a triggered email, use the following URL pattern:

https://api.bluefox.email/v1/send-triggered

Replace the placeholders with your specific information:

##EMAIL_ID##
##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button on a triggered email card:

In the code guide dialog, these values are automatically filled in. If you copy the code snippets, you need to replace the ##YOUR_API_KEY##.

Screenshot of a code guide dialog of a triggered email

Request body:

json

{
  "emails": ["jon@doe.com"],
  "triggeredId": "##EMAIL_ID##",
  "data": {
    "example": "example merge tag value"
  },
  "attachments": [] //optional  
}

You can include personalization data (merge tags) in the data object. These tags are processed by Handlebars when sent.

cUrl:

bash

curl -X POST \
"https://api.bluefox.email/v1/send-triggered" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ##YOUR_API_KEY##" \
-d '{
  "emails": ["jon@doe.com"], // TODO change email addresses
  "triggeredId": ##EMAIL_ID##,
  "data": {
    // TODO add the merge tags values
  }
}'

Javascript:

javascript

const url = 'https://api.bluefox.email/v1/send-triggered'
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ##YOUR_API_KEY##' // TODO change YOUR_APIKEY
  },
  body: JSON.stringify({
    emails: ['jon@doe.com'], // TODO change email address
    triggeredId: "##EMAIL_ID##",
    data: {
    // TODO add the merge tags values
    }
  })
})

PHP:

php

$apiKey = "##YOUR_API_KEY##";

$url = "https://api.bluefox.email/v1/send-triggered";

$emails = ["jon@doe.com"]; // TODO change email addresses
$triggeredId = "##EMAIL_ID##"
$data = [
  // TODO add the merge tags values
];

$payload = json_encode([
  "emails" => $emails,
  "triggeredId" => $triggeredId,
  "data" => $data
]);

$options = [
  "http" => [
    "header"  => [
      "Content-Type: application/json",
      "Authorization: Bearer $apiKey"
    ],
    "method"  => "POST",
    "content" => $payload,
  ],
];

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);

Send attachments

Attachments in bluefox.email allow you to include files in your emails. These files are specified as an array of objects, with each object representing a single attachment. Attachments can be used in both transactional and triggered emails.

WARNING

Attachments are cached for 1 hour. If your email sending process is expected to take longer than an hour, please contact our support team to ensure uninterrupted delivery.

Attachment Object Structure

Each attachment object includes the following fields:

Field	Type	Description	Required
`fileName`	String	The name of the file, including the file extension (e.g., `report.pdf`).	Yes
`content`	String	The file content encoded in Base64 format.	Yes

Example

Here’s an example of how to structure attachments:

json

{
  "attachments": [
    {
      "fileName": "example.txt",
      "content": "Ymx1ZWZveC5lbWFpbCBhdHRhY2htZW50IGV4YW1wbGUh"
    }
  ]
}

Webhook

Webhooks allow your application to receive real-time notifications about events such as email opens, clicks, bounces, complaints, subscriptions, and more. By setting up a webhook, you can stay informed and integrate email event data directly into your application.

Features of Webhooks

Real-Time Updates: Receive immediate notifications about email events.
Customizable Events: Choose the specific events you wish to track.
Secure Communication: Verify incoming requests using a secret key to ensure they are from a trusted source.
Easy Integration: Seamlessly integrate webhook notifications into your app.

Steps to Add a Webhook

Navigate to the Webhooks Section
Go to you project settings and scroll down to the Webhooks section.
Add Webhook URL
Enter the URL where you want to receive event notifications. Ensure your endpoint is able to handle POST requests.
Select Events
Choose the events you want to monitor, such as email opens, clicks, or bounces.
Save and Obtain the Secret Key
After saving, a secret key will be displayed. Copy and securely store this key, as it will be used to verify webhook requests in your endpoint.
Test Webhook
Use the "Test Webhook" feature to simulate a webhook request and verify your setup.
Start Receiving Notifications
Your endpoint will now receive real-time POST requests with event details.

Verifying Webhook Requests

Webhook requests are authenticated using an API key sent in the Authorization header in Bearer token format. You can select in the project settings which API key you want to send with the request. This API key is used to verify the authenticity of the request.

Request Headers

Authorization: Contains the apiKey in the format Bearer your-secret-key.

Steps to Verify Requests

Extract the apikey
Retrieve the apikey from the Authorization header.

Compare the Token
Simply compare the apikey with your predefined apikey

Javascript:

javascript


function verifyRequest(req) {
 const apiKey = 'your-webhook-selected-apikey' // Your predefined API key
 const reqApiKey = req.headers['Authorization']?.split(' ')[1]; // Extract the API key
 if (!reqApiKey) {
     throw new Error('Missing Authorization header');
 }
  return reqApiKey === validApiKey // Check if the provided API key matches the predefined one
}
 verifyRequest(req)

PHP:

php


function verifyRequest($headers) {
  $validApiKey = 'your-webhook-selected-apikey'; // Your predefined API key

  if (!isset($headers['Authorization'])) {
      throw new Exception('Missing Authorization header');
  }

  $apiKey = str_replace('Bearer ', '', $headers['Authorization']); // Extract the API key

  return $apiKey === $validApiKey; // Check if the provided API key matches the predefined one
}

verifyRequest($request);

Respond to the Webhook
If the request is valid, respond with a 200 OK status code.

Zero downtime API key rotation.

To ensure a smooth transition when switching to a new API key, compare the request against multiple keys to prevent downtime.

Below is a JavaScript code snippet to verify webhook:

Javascript:

javascript


 function verifyRequest(req) {
   const validKeys = ['your-webhook-selected-apikey', 'apikey']; // List of valid keys
   const apiKey = req.headers['Authorization']?.split(' ')[1]; // Extract apiKey
   if (!apiKey) {
       throw new Error('Missing Authorization header');
   }
   return validKeys.includes(apiKey);
 }
   verifyRequest(req)

PHP:

php


  function verifyRequest($headers) {
    $validKeys = ['your-webhook-selected-apikey', 'apikey']; // List of valid keys

    if (!isset($headers['Authorization'])) {
        throw new Exception('Missing Authorization header');
    }

    $apiKey = str_replace('Bearer ', '', $headers['Authorization']); // Extract apiKey

    return in_array($apiKey, $validKeys, true);
  }

  verifyRequest($request);

Example of webhook event types body

When the webhook is triggered, the body of the request will contain information about the event. Here's an example of the payload you might receive:

Sent event

json

{
  "type": "sent",
  "account": { "name": "Account name", "urlFriendlyName": "UrlFriendlyName" },
  "project": { "name": "Project name "},
  "createdAt": "2025-01-06T13:27:32.017Z",
  "emailData": {
    "sentAt": "2025-01-06T13:27:32.017Z",
    "to": "test@gmail.com",
    "type": "e.g. transactional, triggered or campaign",
    "subject": "This is bluefox.email webhook test"
  },
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36",
  "referer": "https://www.example.com/some-page",
  "ipAddress": "203.0.113.195",
}

Failed event

json

{
  "type": "failed",
  "account": { "_id": "accountId", "name": "Account name", "urlFriendlyName": "UrlFriendlyName" },
  "project": { "_id": "projectId", "name": "Project name "},
  "createdAt": "2025-01-06T13:27:32.017Z",
  "emailData": {
    "_id": "emailId",
    "sentAt": "2025-01-06T13:27:32.017Z",
    "to": "test@gmail.com",
    "type": "e.g. transactional, triggered or campaign",
    "subject": "This is bluefox.email webhook test"
  },
  "errors": ["error object"],
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36",
  "referer": "https://www.example.com/some-page",
  "ipAddress": "203.0.113.195",
}

Click event

json

{
  "type": "click",
  "account": { "_id": "accountId", "name": "Account name", "urlFriendlyName": "UrlFriendlyName" },
  "project": { "_id": "projectId", "name": "Project name "},
  "createdAt": "2025-01-06T13:27:32.017Z",
  "emailData": {
    "_id": "emailId",
    "sentAt": "2025-01-06T13:27:32.017Z",
    "to": "test@gmail.com",
    "type": "e.g. transactional, triggered or campaign",
    "subject": "This is bluefox.email webhook test"
  },
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36",
  "referer": "https://www.example.com/some-page",
  "ipAddress": "203.0.113.195",
  "blockPosition": "Block position e.g. 1",
  "blockName": "Block name e.g. Hero",
  "link": "https://www.example.com/btn-link"
}

Open event

json

{
  "type": "open",
  "account": { "_id": "accountId", "name": "Account name", "urlFriendlyName": "UrlFriendlyName" },
  "project": { "_id": "projectId", "name": "Project name "},
  "createdAt": "2025-01-06T13:27:32.017Z",
  "emailData": {
    "_id": "emailId",
    "sentAt": "2025-01-06T13:27:32.017Z",
    "to": "test@gmail.com",
    "type": "e.g. transactional, triggered or campaign",
    "subject": "This is bluefox.email webhook test"
  },
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36",
  "referer": "https://www.example.com/some-page",
  "ipAddress": "203.0.113.195",
}

Bounce event

json

{
  "type": "bounce",
  "account": { "_id": "accountId", "name": "Account name", "urlFriendlyName": "UrlFriendlyName" },
  "project": { "_id": "projectId", "name": "Project name "},
  "createdAt": "2025-01-06T13:27:32.017Z",
  "emailData": {
    "_id": "emailId",
    "sentAt": "2025-01-06T13:27:32.017Z",
    "to": "test@gmail.com",
    "type": "e.g. transactional, triggered or campaign",
    "subject": "This is bluefox.email webhook test"
  },
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36",
  "referer": "https://www.example.com/some-page",
  "ipAddress": "203.0.113.195",
}

Complaint event

json

{
  "type": "complaint",
  "account": { "_id": "accountId", "name": "Account name", "urlFriendlyName": "UrlFriendlyName" },
  "project": { "_id": "projectId", "name": "Project name "},
  "createdAt": "2025-01-06T13:27:32.017Z",
  "emailData": {
    "_id": "emailId",
    "sentAt": "2025-01-06T13:27:32.017Z",
    "to": "test@gmail.com",
    "type": "e.g. transactional, triggered or campaign",
    "subject": "This is bluefox.email webhook test"
  },
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.82 Safari/537.36",
  "referer": "https://www.example.com/some-page",
  "ipAddress": "203.0.113.195",
}

Subscription event

json

{
"type": "pause-subscription, unsubscribe, subscribe' or resubscribe",
  "account": { "name": "Account name", "urlFriendlyName": "UrlFriendlyName" },
  "project": { "name": "Project name "},
  "createdAt": "2025-01-06T13:27:32.017Z",
  "subscription": {
    "_id": "subscriberId",
    "name": "Subscriber name",
    "email": "subscriber@gmail.com",
    "status": "e.g. unsubscribed, paused, active or unverified",
    "subscriberList": {
      "name": "SubscriberList name",
      "_id": "subscriberListId",
      "private": "e.g. true or false"
    }
  },
  "emailData": {
    "_id": "emailId",
    "sentAt": "2025-01-06T13:27:32.017Z",
    "to": "test@gmail.com",
    "type": "e.g. transactional, triggered or campaign",
    "subject": "This is bluefox.email webhook test"
  },
}

Projects

API

Design Systems

API

Update Subscriber

Unsubscribe

Activate Subscription

Pause Subscription

List Subscribers

Get Subscriber

Send transactional email

Send triggered email

Send attachments

Attachment Object Structure

Example

Webhook

Features of Webhooks

Steps to Add a Webhook

Verifying Webhook Requests

Request Headers

Steps to Verify Requests

Javascript:

PHP:

Javascript:

PHP:

Example of webhook event types body

Sent event

Failed event

Click event

Open event

Bounce event

Complaint event

Subscription event

API ​

Subscribe ​

Update Subscriber ​

Unsubscribe ​

Activate Subscription ​

Pause Subscription ​

List Subscribers ​

Get Subscriber ​

Send transactional email ​

Send triggered email ​

Send attachments ​

Attachment Object Structure ​

Example ​

Webhook ​

Features of Webhooks ​

Steps to Add a Webhook ​

Verifying Webhook Requests ​

Request Headers ​

Steps to Verify Requests ​

Javascript: ​

PHP: ​

Javascript: ​

PHP: ​

Example of webhook event types body ​

Sent event ​

Failed event ​

Click event ​

Open event ​

Bounce event ​

Complaint event ​

Subscription event ​

API

Subscribe

Update Subscriber

Unsubscribe

Activate Subscription

Pause Subscription

List Subscribers

Get Subscriber

Send transactional email

Send triggered email

Send attachments

Attachment Object Structure

Example

Webhook

Features of Webhooks

Steps to Add a Webhook

Verifying Webhook Requests

Request Headers

Steps to Verify Requests

Javascript:

PHP:

Javascript:

PHP:

Example of webhook event types body

Sent event

Failed event

Click event

Open event

Bounce event

Complaint event

Subscription event