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.

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"
    }
  ]
}

Projects

Design Systems

API

Unsubscribe

Activate Subscription

Pause Subscription

List Subscribers

Get Subscriber

Send transactional email

Send triggered email

Send attachments

Attachment Object Structure

Example

API ​

Subscribe ​

Unsubscribe ​

Activate Subscription ​

Pause Subscription ​

List Subscribers ​

Get Subscriber ​

Send transactional email ​

Send triggered email ​

Send attachments ​

Attachment Object Structure ​

Example ​

API

Subscribe

Unsubscribe

Activate Subscription

Pause Subscription

List Subscribers

Get Subscriber

Send transactional email

Send triggered email

Send attachments

Attachment Object Structure

Example