Contacts API examples

Create a contact

loops contacts create \
  --email test@example.com \
  --first-name John \
  --last-name Doe

const response = await fetch("https://app.loops.so/api/v1/contacts/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "test@example.com",
    firstName: "John",
    lastName: "Doe",
  }),
});

const data = await response.json();

import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.createContact(
  "test@example.com",
  {
    firstName: "John",
    lastName: "Doe"
  },
);

use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->create(
  email: 'test@example.com',
  properties: [
    'firstName' => 'John',
    'lastName' => 'Doe',
  ],
);

response = LoopsSdk::Contacts.create(
  email: "test@example.com",
  properties: {
    firstName: "John",
    lastName: "Doe",
  },
)

import requests

response = requests.post(
    "https://app.loops.so/api/v1/contacts/create",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "firstName": "John",
        "lastName": "Doe"
    }
)

Create a contact and add them to a mailing list

API reference
CLI reference

loops contacts create \
  --email test@example.com \
  --first-name John \
  --last-name Doe \
  --list "<mailing-list-id>=true"

const response = await fetch("https://app.loops.so/api/v1/contacts/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "test@example.com",
    firstName: "John",
    lastName: "Doe",
    mailingLists: {
      "<mailing-list-id>": true
    },
  }),
});

const data = await response.json();

import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const properties = {
  firstName: "John",
  lastName: "Doe",
};

const mailingLists = {
  "<mailing-list-id>": true,
};

const response = await loops.createContact(
  "test@example.com",
  properties,
  mailingLists,
);

use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->create(
  email: 'test@example.com',
  properties: [
    'firstName' => 'John',
    'lastName' => 'Doe',
  ],
  mailing_lists: [
    '<mailing-list-id>' => TRUE,
  ],
);

response = LoopsSdk::Contacts.create(
  email: "test@example.com",
  properties: {
    firstName: "John",
    lastName: "Doe",
  },
  mailing_lists: {
    "<mailing-list-id>": true,
  },
)

import requests

response = requests.post(
    "https://app.loops.so/api/v1/contacts/create",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "mailingLists": {
            "<mailing-list-id>": True
        }
    }
)

Update a contact

When updating a contact you must provide an email or userId value to identify the contact.

You can use the “update” endpoint to update or create contacts. If the provided email or user ID does not exist, a new contact will be created.

API reference
CLI reference

loops contacts update \
  --email test@example.com \
  --prop planName=Pro

const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
    planName: "Pro",
  }),
});

const data = await response.json();

import { LoopsClient } from "loops";  

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact(
  "test@example.com",
  {
    planName: "Pro",
  },
);

use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  properties: [
    'planName' => 'Pro',
  ],
);

response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  properties: {
    planName: "Pro",
  },
)

import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "planName": "Pro"
    }
)

Update a contact’s email address

For this the contact will need to already have a userId value set. API reference
CLI reference

loops contacts update \
  --user-id 12345 \
  --email test@example.com

const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    userId: "12345",
    email: "test@example.com",
  }),
});

const data = await response.json();

import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact(
  "test@example.com",
  {
    userId: "12345",
  },
);

use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  properties: [
    'userId' => '12345',
  ],
);

response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  properties: {
    userId: "12345",
  },
)

import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "userId": "12345"
    }
)

API reference
CLI reference

loops contacts update \
  --email test@example.com \
  --list "<mailing-list-id>=true"

const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
    mailingLists: {
      "<mailing-list-id>" => true
    },
  }),
});

const data = await response.json();

import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact(
  "test@example.com",
  {},
  {
    "<mailing-list-id>": true,
  },
);

use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  mailing_lists: [
    '<mailing-list-id>' => TRUE,
  ],
);

response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  mailing_lists: {
    "<mailing-list-id>" => true,
  },
)

import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "mailingLists": {
            "<mailing-list-id>": True
        }
    }
)

Unsubscribe a contact from a mailing list

This removes a contact from a specific mailing list. See below to see how to fully unsubscribe a contact. Use false to unsubscribe a contact from a mailing list. API reference
CLI reference

loops contacts update \
  --email test@example.com \
  --list "<mailing-list-id>=false"

const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
    mailingLists: {
      "<mailing-list-id>" => false
    },
  }),
});

const data = await response.json();

import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact(
  "test@example.com",
  {},
  {
    "<mailing-list-id>" => false,
  },
);

use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  mailing_lists: [
    '<mailing-list-id>' => FALSE,
  ],
);

response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  mailing_lists: {
    "<mailing-list-id>" => false,
  },
)

import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "mailingLists": {
            "<mailing-list-id>": False
        }
    }
)

Unsubscribe a contact

Set subscribed to false to unsubscribe a contact. The contact will no longer receive campaign or workflow emails, but will remain listed in your audience. API reference
CLI reference

loops contacts update \
  --email test@example.com \
  --subscribed false

const response = await fetch("https://app.loops.so/api/v1/contacts/update", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
    subscribed: false,
  }),
});

const data = await response.json();

import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.updateContact(
  "test@example.com",
  {
    subscribed: false,
  },
);

use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->update(
  email: 'test@example.com',
  subscribed: false,
);

response = LoopsSdk::Contacts.update(
  email: "test@example.com",
  subscribed: false,
)

import requests

response = requests.put(
    "https://app.loops.so/api/v1/contacts/update",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
        "subscribed": False
    }
)

Delete a contact

You can delete contacts by email or user ID. API reference
CLI reference

loops contacts delete --email test@example.com

const response = await fetch("https://app.loops.so/api/v1/contacts/delete", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "test@example.com",
  }),
});

const data = await response.json();

import { LoopsClient } from "loops";

const loops = new LoopsClient("<your-api-key>");

const response = await loops.deleteContact({
  email: "test@example.com",
});

use Loops\LoopsClient;

$loops = new LoopsClient("<your-api-key>");

$result = $loops->contacts->delete(
  email: 'test@example.com',
);

response = LoopsSdk::Contacts.delete(
  email: "test@example.com",
)

import requests

response = requests.post(
    "https://app.loops.so/api/v1/contacts/delete",
    headers={
        "Authorization": "Bearer <your-api-key>",
        "Content-Type": "application/json"
    },
    json={
        "email": "test@example.com",
    }
)

Check contact suppression status

API reference
CLI reference

loops contacts suppression check --email test@example.com

const params = new URLSearchParams({ email: "test@example.com" });

const response = await fetch(
  `https://app.loops.so/api/v1/contacts/suppression?${params.toString()}`,
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer <your-api-key>",
    },
  },
);

const data = await response.json();

import requests

response = requests.get(
    "https://app.loops.so/api/v1/contacts/suppression",
    headers={
        "Authorization": "Bearer <your-api-key>",
    },
    params={
        "email": "test@example.com",
    },
)

data = response.json()

Remove suppression for a contact

API reference
CLI reference

loops contacts suppression remove --email test@example.com

const params = new URLSearchParams({ email: "test@example.com" });

const response = await fetch(
  `https://app.loops.so/api/v1/contacts/suppression?${params.toString()}`,
  {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer <your-api-key>",
    },
  },
);

const data = await response.json();

import requests

response = requests.delete(
    "https://app.loops.so/api/v1/contacts/suppression",
    headers={
        "Authorization": "Bearer <your-api-key>",
    },
    params={
        "email": "test@example.com",
    },
)

data = response.json()

Learn

API

CLI

Guides

Contacts API examples

Create a contact

Create a contact and add them to a mailing list

Update a contact

Update a contact’s email address

Unsubscribe a contact from a mailing list

Unsubscribe a contact

Delete a contact

Check contact suppression status

Remove suppression for a contact

​Create a contact

​Create a contact and add them to a mailing list

​Update a contact

​Update a contact’s email address

​Subscribe a contact to a mailing list

​Unsubscribe a contact from a mailing list

​Unsubscribe a contact

​Delete a contact

​Check contact suppression status

​Remove suppression for a contact

Create a contact

Create a contact and add them to a mailing list

Update a contact

Update a contact’s email address

Subscribe a contact to a mailing list

Unsubscribe a contact from a mailing list

Unsubscribe a contact

Delete a contact

Check contact suppression status

Remove suppression for a contact