JavaScript SDK
Installation
You can install the package from npm:
npm install loops
You will need a Loops API key to use the package.
In your Loops account, go to the API Settings page and click “Generate key”.
Copy this key and save it in your application code (for example as LOOPS_API_KEY in an .env file).
See the API documentation to learn more about rate limiting and error handling.
Usage
import LoopsClient from "loops";
const loops = new LoopsClient(process.env.LOOPS_API_KEY);
const resp = await loops.createContact("[email protected]");
Default contact properties
Each contact in Loops has a set of default properties. These will always be returned in API results.
idemailfirstNamelastNamesourcesubscribeduserGroupuserId
Custom contact properties
You can use custom contact properties in API calls. Please make sure to add custom properties in your Loops account before using them with the SDK.
Methods
- createContact()
- updateContact()
- findContact()
- deleteContact()
- sendEvent()
- sendTransactionalEmail()
- getCustomFields()
createContact()
Create a new contact.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
email | string | Yes | If a contact already exists with this email address, an error response will be returned. |
properties | object | No | An object containing default and any custom properties for your contact. Please add custom properties in your Loops account before using them with the SDK. Values can be of type string, number or boolean. |
Examples
const resp = await loops.createContact("[email protected]");
const contactProperties = {
firstName: "Bob" /* Default property */,
favoriteColor: "Red" /* Custom property */,
};
const resp = await loops.createContact("[email protected]", contactProperties);
Response
This method will return a success or error message:
{
"success": true,
"id": "id_of_contact"
}
{
"success": false,
"message": "An error message here."
}
updateContact()
Update a contact.
Note: To update a contact’s email address, the contact requires a userId value. Then you can make a request with their userId and an updated email address.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
email | string | Yes | The email address of the contact to update. If there is no contact with this email address, a new contact will be created using the email and properties in this request. |
properties | object | No | An object containing default and any custom properties for your contact. Please add custom properties in your Loops account before using them with the SDK. Values can be of type string, number or boolean. |
Example
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",
});
Response
This method will return a success or error message:
{
"success": true,
"id": "id_of_contact"
}
{
"success": false,
"message": "An error message here."
}
findContact()
Find a contact by email address.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
email | string | Yes |
Example
const resp = await loops.findContact("[email protected]");
Response
This method will return a list containing a single contact object, which will include all default properties and any custom properties.
If no contact is found, an empty list will be returned.
[
{
"id": "cll6b3i8901a9jx0oyktl2m4u",
"email": "[email protected]",
"firstName": "Bob",
"lastName": null,
"source": "API",
"subscribed": true,
"userGroup": "",
"userId": null,
"favoriteColor": "Blue" /* Custom property */
}
]
deleteContact()
Delete a contact, either by email address or userId.
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
email | string | No | |
userId | string | No |
Example
const resp = await loops.deleteContact({ email: "[email protected]" });
const resp = await loops.deleteContact({ userId: "abcd" });
Response
This method will return a success or error message:
{
"success": true,
"message": "Contact deleted."
}
{
"success": false,
"message": "An error message here."
}
sendEvent()
Send an event to trigger an email in Loops. Read more about triggering emails
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
email | string | Yes | If there is no contact with this email address, a new contact will be created. |
eventName | string | Yes | |
properties | object | No | An object containing contact properties, which will be updated or added to the contact when the event is received. Please add custom properties in your Loops account before using them with the SDK. Values can be of type string, number or boolean. |
Examples
const resp = await loops.sendEvent("[email protected]", "signup");
const resp = await loops.sendEvent("[email protected]", "signup", {
firstName: "Bob",
plan: "pro",
});
Response
This method will return a success or error:
{
"success": true
}
{
"success": false
}
sendTransactionalEmail()
Send a transactional email to a contact. Learn about sending transactional email
Parameters
| Name | Type | Required | Notes |
|---|---|---|---|
transactionalId | string | Yes | The ID of the transactional email to send. |
email | string | Yes | If there is no contact with this email address, a new contact will be created. |
dataVariables | object | No | An object containing data as defined by the data variables added to the transactional email template. Values can be of type string or number. |
attachments | object[] | No | A list of attachments objects. Please note: Attachments need to be enabled on your account before using them with the API. Read more |
attachments[].filename | string | No | The name of the file, shown in email clients. |
attachments[].contentType | string | No | The MIME type of the file. |
attachments[].data | string | No | The base64-encoded content of the file. |
Example
const dataVariables = {
loginUrl: "https://myapp.com/login/",
};
const resp = await loops.sendTransactionalEmail(
"clfq6dinn000yl70fgwwyp82l",
"[email protected]",
dataVariables
);
// Please contact us to enable attachments on your account.
const attachments = [
{
filename: "presentation.pdf",
contentType: "application/pdf",
data: "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPD..."
}
];
const resp = await loops.sendTransactionalEmail(
"clfq6dinn000yl70fgwwyp82l",
"[email protected]",
dataVariables,
attachments
);
Response
This method will return a success or error message.
{
"success": true
}
If there is a problem with the request, a descriptive error message will be returned:
{
"success": false,
"path": "dataVariables",
"message": "There are required fields for this email. You need to include a 'dataVariables' object with the required fields."
}
{
"success": false,
"error": {
"path": "dataVariables",
"message": "Missing required fields: login_url"
},
"transactionalId": "clfq6dinn000yl70fgwwyp82l"
}
getCustomFields()
Get a list of your account’s custom fields. These are custom properties that can be added to contacts to store extra data. Read more about contact properties
Parameters
None
Example
const resp = await loops.getCustomFields();
Response
This method will return a list of custom field objects containing key and label attributes.
If there are no custom fields, an empty list will be returned.
[
{
"key": "favoriteColor",
"label": "Favourite Color"
},
{
"key": "plan",
"label": "Plan"
}
]
Version history
v0.1.3(Dec 8, 2023) - Added support for transactional attachments.v0.1.2(Dec 6, 2023) - Improved transactional error types.v0.1.1(Nov 1, 2023) - Initial release.
Was this page helpful?