JavaScript SDK

npm install loops

import { LoopsClient, APIError } from "loops";

const loops = new LoopsClient(process.env.LOOPS_API_KEY);

try {
  const resp = await loops.createContact("[email protected]");
  // resp.success and resp.id available when successful
} catch (error) {
  if (error instanceof APIError) {
    // JSON returned by the API is in error.json and the HTTP code is in error.statusCode
    // Error messages explaining the issue can be found in error.json.message
    console.log(error.json);
    console.log(error.statusCode);
  } else {
    // Non-API errors
  }
}

import { LoopsClient, APIError, RateLimitExceededError } from "loops";

const loops = new LoopsClient(process.env.LOOPS_API_KEY);

try {
  const resp = await loops.createContact("[email protected]");
} catch (error) {
  if (error instanceof RateLimitExceededError) {
    console.log(`Rate limit exceeded (${error.limit} per second)`);
    // Code here to re-try this request
  } else {
    // Handle other errors
  }
}

const resp = await loops.testApiKey();

{
  "success": true,
  "teamName": "My team"
}

HTTP 401 Unauthorized
{
  "error": "Invalid API key"
}

const resp = await loops.createContact("[email protected]");

const contactProperties = {
  firstName: "Bob" /* Default property */,
  favoriteColor: "Red" /* Custom property */,
};
const mailingLists = {
  cm06f5v0e45nf0ml5754o9cix: true,
  cm16k73gq014h0mmj5b6jdi9r: false,
};
const resp = await loops.createContact(
  "[email protected]",
  contactProperties,
  mailingLists
);

{
  "success": true,
  "id": "id_of_contact"
}

HTTP 400 Bad Request
{
  "success": false,
  "message": "An error message here."
}

const contactProperties = {
  firstName: "Bob" /* Default property */,
  favoriteColor: "Blue" /* Custom property */,
};
const resp = await loops.updateContact("[email protected]", contactProperties);

/* Updating a contact's email address using userId */
const resp = await loops.updateContact("[email protected]", {
  userId: "1234",
});

{
  "success": true,
  "id": "id_of_contact"
}

HTTP 400 Bad Request
{
  "success": false,
  "message": "An error message here."
}

const resp = await loops.findContact({ email: "[email protected]" });

const resp = await loops.findContact({ userId: "12345" });

[
  {
    "id": "cll6b3i8901a9jx0oyktl2m4u",
    "email": "[email protected]",
    "firstName": "Bob",
    "lastName": null,
    "source": "API",
    "subscribed": true,
    "userGroup": "",
    "userId": "12345",
    "mailingLists": {
      "cm06f5v0e45nf0ml5754o9cix": true
    },
    "favoriteColor": "Blue" /* Custom property */
  }
]

const resp = await loops.deleteContact({ email: "[email protected]" });

const resp = await loops.deleteContact({ userId: "12345" });

{
  "success": true,
  "message": "Contact deleted."
}

HTTP 400 Bad Request
{
  "success": false,
  "message": "An error message here."
}

HTTP 404 Not Found
{
  "success": false,
  "message": "An error message here."
}

const resp = await loops.createContactProperty("planName", "string");

{
  "success": true
}

HTTP 400 Bad Request
{
  "success": false,
  "message": "An error message here."
}

const resp = await loops.getContactProperties();

const resp = await loops.getContactProperties("custom");

[
  {
    "key": "firstName",
    "label": "First Name",
    "type": "string"
  },
  {
    "key": "lastName",
    "label": "Last Name",
    "type": "string"
  },
  {
    "key": "email",
    "label": "Email",
    "type": "string"
  },
  {
    "key": "notes",
    "label": "Notes",
    "type": "string"
  },
  {
    "key": "source",
    "label": "Source",
    "type": "string"
  },
  {
    "key": "userGroup",
    "label": "User Group",
    "type": "string"
  },
  {
    "key": "userId",
    "label": "User Id",
    "type": "string"
  },
  {
    "key": "subscribed",
    "label": "Subscribed",
    "type": "boolean"
  },
  {
    "key": "createdAt",
    "label": "Created At",
    "type": "date"
  },
  {
    "key": "favoriteColor",
    "label": "Favorite Color",
    "type": "string"
  },
  {
    "key": "plan",
    "label": "Plan",
    "type": "string"
  }
]

const resp = await loops.getMailingLists();

[
  {
    "id": "cm06f5v0e45nf0ml5754o9cix",
    "name": "Main list",
    "description": "All customers.",
    "isPublic": true
  },
  {
    "id": "cm16k73gq014h0mmj5b6jdi9r",
    "name": "Investors",
    "description": null,
    "isPublic": false
  }
]

const resp = await loops.sendEvent({
  email: "[email protected]",
  eventName: "signup",
});

const resp = await loops.sendEvent({
  email: "[email protected]",
  eventName: "signup",
  eventProperties: {
    username: "user1234",
    signupDate: "2024-03-21T10:09:23Z",
  },
  mailingLists: {
    cm06f5v0e45nf0ml5754o9cix: true,
    cm16k73gq014h0mmj5b6jdi9r: false,
  },
});

// In this case with both email and userId present, the system will look for a contact with either a
//  matching `email` or `userId` value.
// If a contact is found for one of the values (e.g. `email`), the other value (e.g. `userId`) will be updated.
// If a contact is not found, a new contact will be created using both `email` and `userId` values.
// Any values added in `contactProperties` will also be updated on the contact.
const resp = await loops.sendEvent({
  userId: "1234567890",
  email: "[email protected]",
  eventName: "signup",
  contactProperties: {
    firstName: "Bob",
    plan: "pro",
  },
});

{
  "success": true
}

HTTP 400 Bad Request
{
  "success": false,
  "message": "An error message here."
}

const resp = await loops.sendTransactionalEmail({
  transactionalId: "clfq6dinn000yl70fgwwyp82l",
  email: "[email protected]",
  dataVariables: {
    loginUrl: "https://myapp.com/login/",
  },
});

// Please contact us to enable attachments on your account.
const resp = await loops.sendTransactionalEmail({
  transactionalId: "clfq6dinn000yl70fgwwyp82l",
  email: "[email protected]",
  dataVariables: {
    loginUrl: "https://myapp.com/login/",
  },
  attachments: [
    {
      filename: "presentation.pdf",
      contentType: "application/pdf",
      data: "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPD...",
    },
  ],
});

{
  "success": true
}

HTTP 400 Bad Request
{
  "success": false,
  "path": "dataVariables",
  "message": "There are required fields for this email. You need to include a 'dataVariables' object with the required fields."
}

HTTP 400 Bad Request
{
  "success": false,
  "error": {
    "path": "dataVariables",
    "message": "Missing required fields: login_url"
  },
  "transactionalId": "clfq6dinn000yl70fgwwyp82l"
}