Contacts and Contact Management via the API ​

Legacy endpoint. New integrations should use the Contacts resource instead.

This guide explains how to manage contacts using the bluefox.email API. You can create, retrieve, update, and delete contacts from your project. Follow the examples and code snippets to integrate these functionalities into your system.

Create Contact ​

Quick guide

To create a new contact in your project, use the following URL pattern:

https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##

Replace the placeholders with your specific information:

  • ##YOUR_PROJECT_ID##
  • ##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in your contacts section:

Screenshot of the highlighted code guide button in contacts.

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 for creating a contact.

Request Body:

json
{
  "email": "jon@doe.com",
  "name": "Jon Doe",
  // Add more fields as needed
}

INFO

You can pass values for contact custom properties inside the data field in the request body. Just make sure the keys match the custom property API names defined in your project settings.

cUrl:

bash
curl -X POST "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" -d '{"name": "userName", "email": "example@gmail.com"}'

Javascript:

javascript
const url = `https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##`;
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_APIKEY' // TODO include the authorization when using the code from the backend and replace YOUR_APIKEY
    },
    body: JSON.stringify({
      email: 'example@gmail.com',
      name: 'userName',
      // Add more fields as needed
    })
  });

PHP:

php
$apiKey = 'YOUR_API_KEY'; // TODO: Replace YOUR_APIKEY

$url = "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##";

$data = array(
  'email' => 'example@gmail.com',
  'name' => 'userName',
  // Add more fields as needed
);

$options = array(
    'http' => array(
        'header'  => "Content-Type: application/json" .
                    "Authorization: Bearer $apiKey",
        '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.

List Contacts ​

Quick guide

To retrieve all contacts from your project, use the following URL pattern:

https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##

Replace the placeholders with your specific information:

  • ##YOUR_PROJECT_ID##
  • ##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in your contacts section:

Screenshot of the highlighted code guide button in contacts.

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 for listing contacts.

cUrl:

bash
curl -X GET "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY"

Javascript:

javascript
const url = `https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##`;
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_APIKEY' // TODO include the authorization when using the code from the backend and replace YOUR_APIKEY
    }
  });

PHP:

php
$apiKey = 'YOUR_API_KEY'; // TODO: Replace YOUR_APIKEY

$url = "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##";

$options = array(
    'http' => array(
        'header'  => "Content-Type: application/json" .
                    "Authorization: Bearer $apiKey",
        '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 One Contact ​

Quick guide

To retrieve a specific contact from your project, use the following URL pattern:

https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##

Replace the placeholders with your specific information:

  • ##YOUR_PROJECT_ID##
  • ##CONTACT_EMAIL_ADDRESS##
  • ##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in your contacts section:

Screenshot of the highlighted code guide button in contacts.

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 ##CONTACT_EMAIL_ADDRESS##.

Screenshot of the code guide dialog for getting one contact.

cUrl:

bash
curl -X GET "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY"

Javascript:

javascript
const url = `https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##`;
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_APIKEY' // TODO include the authorization when using the code from the backend and replace YOUR_APIKEY
    }
  });

PHP:

php
$apiKey = 'YOUR_API_KEY'; // TODO: Replace YOUR_APIKEY

$url = "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##";

$options = array(
    'http' => array(
        'header'  => "Content-Type: application/json" .
                    "Authorization: Bearer $apiKey",
        '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.

Update Contact ​

Quick guide

To update a contact in your project, use the following URL pattern:

https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##

Replace the placeholders with your specific information:

  • ##YOUR_PROJECT_ID##
  • ##CONTACT_EMAIL_ADDRESS##
  • ##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in your contacts section:

Screenshot of the highlighted code guide button in contacts.

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 ##CONTACT_EMAIL_ADDRESS##.

Screenshot of the code guide dialog for updating a contact.

Request body:

json
{
  "email": "updated_email@gmail.com",
  "name": "Updated Name",
   // Add more fields as needed
}

INFO

You can pass values for contact custom properties inside the data field in the request body. Just make sure the keys match the custom property API names defined in your project settings.

cUrl:

bash
curl -X PATCH "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY" -d '{"name": "updatedName"}'

Javascript:

javascript
//TODO replace subscriber email
  const url = `https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##`;
  const response = await fetch(url, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_APIKEY' // TODO include the authorization when using the code from the backend and replace YOUR_APIKEY
    },
    body: JSON.stringify({
      name: 'updatedName'
    })
  });

PHP:

php
// TODO: Replace YOUR_APIKEY and subscriber email
$apiKey = 'YOUR_API_KEY';

$url = "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##";

$data = array(
    'name' => 'updatedName'
);

$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.

Delete Contact ​

Quick guide

To delete a contact from your project, use the following URL pattern:

https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##

Replace the placeholders with your specific information:

  • ##YOUR_PROJECT_ID##
  • ##CONTACT_EMAIL_ADDRESS##
  • ##YOUR_API_KEY##

You can find the IDs to replace by clicking on the code guide button in your contacts section:

Screenshot of the highlighted code guide button in contacts.

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 ##CONTACT_EMAIL_ADDRESS##.

Screenshot of the code guide dialog for deleting a contact.

cUrl:

bash
curl -X DELETE "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##" -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_API_KEY"

Javascript:

javascript
const url = `https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##`;
  const response = await fetch(url, {
    method: 'DELETE',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_APIKEY' // TODO include the authorization when using the code from the backend and replace YOUR_APIKEY
    }
  });

PHP:

php
$apiKey = 'YOUR_API_KEY'; // TODO: Replace YOUR_APIKEY

$url = "https://api.bluefox.email/v1/contacts/##YOUR_PROJECT_ID##/##CONTACT_EMAIL_ADDRESS##";

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

$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.

API Responses ​

CodeNameMessageDescriptionJSON Response Example
200--The request was successfully processed.json { "status": 200, "result": { "accountId": "account_id", "projectId": "project_id", "name": "name", "email": "example@gmail.com", "_id": "contact_id", "createdAt": "Date", "updatedAt": "Date" } }
201--A new contact has been created as a result of the request.json { "status": 201, "result": { "accountId": "account_id", "projectId": "project_id", "name": "name", "email": "example@gmail.com", "_id": "contact_id", "createdAt": "Date", "updatedAt": "Date" } }
400VALIDATION_ERROREmail already exists.The email address is already registered in the system.json { "status": 400, "error": { "name": "VALIDATION_ERROR", "message": "Email already exists." } }
400VALIDATION_ERRORInvalid email formatThe request contains improperly formatted email. Ensure email is valid email address.json { "status": 400, "error": { "name": "VALIDATION_ERROR", "message": "Invalid email format" } }
404NOT_FOUNDContact not foundThe requested contact does not exist in the system.json { "status": 404, "error": { "name": "NOT_FOUND", "message": "Contact not found" } }
405METHOD_NOT_ALLOWEDThe provided email has been flagged due to bouncing. If this is incorrect and the email is valid, please contact support.The email address has been marked as undeliverable due to previous failed delivery attempts.json { "status": 405, "error": { "name": "METHOD_NOT_ALLOWED", "message": "The provided email has been flagged due to bouncing. If this is incorrect and the email is valid, please contact support." } }

Frequently Asked Questions

What operations can I perform on contacts via the API?

The contacts API supports create (POST), list all (GET), get one by email (GET), update (PATCH), and delete (DELETE). All endpoints use https://api.bluefox.email/v1/contacts/YOUR_PROJECT_ID as the base, with the contact email address appended for single-contact operations.

How is a contact different from a subscriber in the API?

A contact is a project-level record with an email address and custom properties. A subscriber is that contact's relationship to a specific subscriber list with a status (active, paused, or unsubscribed). The contacts API manages the contact record; the subscriber list management API manages list memberships.

Can I store custom data on a contact via the API?

Yes. Include a data object in the request body with keys matching the API names of your custom contact properties defined in project settings. These values are then available as merge tags in emails and as filter conditions in segments.

What happens if I try to create a contact with an email that already exists?

The API returns a 400 VALIDATION_ERROR with the message Email already exists. Each contact email must be unique within a project. To update an existing contact use the PATCH endpoint instead.