The official Loops SDK for JavaScript, with full TypeScript support.
LOOPS_API_KEY
in an .env
file).
RateLimitExceededError
you can check for rate limit issues with your requests.
You can access details about the rate limits from the limit
and remaining
attributes.
id
email
firstName
lastName
source
subscribed
userGroup
userId
APIError
class, which provides statusCode
and json
properties containing the API’s error response details. For implementation examples, see the Usage section.
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 , null (to reset a value), boolean or date (see allowed date formats). |
mailingLists | object | No | An object of mailing list IDs and boolean subscription statuses. |
APIError
class, which provides statusCode
and json
properties containing the API’s error response details. For implementation examples, see the Usage section.
userId
value. Then you can make a request with their userId
and an updated email address.
API Reference
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 , null (to reset a value), boolean or date (see allowed date formats). |
mailingLists | object | No | An object of mailing list IDs and boolean subscription statuses. |
APIError
class, which provides statusCode
and json
properties containing the API’s error response details. For implementation examples, see the Usage section.
Name | Type | Required | Notes |
---|---|---|---|
email | string | No | |
userId | string | No |
userId
.
API Reference
Name | Type | Required | Notes |
---|---|---|---|
email | string | No | |
userId | string | No |
APIError
class, which provides statusCode
and json
properties containing the API’s error response details. For implementation examples, see the Usage section.
Name | Type | Required | Notes |
---|---|---|---|
name | string | Yes | The name of the property. Should be in camelCase, like planName or favouriteColor . |
type | string | Yes | The property’s value type. Can be one of string , number , boolean or date . |
APIError
class, which provides statusCode
and json
properties containing the API’s error response details. For implementation examples, see the Usage section.
Name | Type | Required | Notes |
---|---|---|---|
list | string | No | Use “custom” to retrieve only your account’s custom properties. |
key
, label
and type
attributes.
id
, name
, description
and isPublic
attributes.
If your account has no mailing lists, an empty list will be returned.
Name | Type | Required | Notes |
---|---|---|---|
email | string | No | The contact’s email address. Required if userId is not present. |
userId | string | No | The contact’s unique user ID. If you use userId without email , this value must have already been added to your contact in Loops. Required if email is not present. |
eventName | string | Yes | |
contactProperties | 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 , null (to reset a value), boolean or date (see allowed date formats). |
eventProperties | object | No | An object containing event properties, which will be made available in emails that are triggered by this event. Values can be of type string , number , boolean or date (see allowed date formats). |
mailingLists | object | No | An object of mailing list IDs and boolean subscription statuses. |
headers | object | No | Additional headers to send with the request. |
APIError
class, which provides statusCode
and json
properties containing the API’s error response details. For implementation examples, see the Usage section.
Name | Type | Required | Notes |
---|---|---|---|
transactionalId | string | Yes | The ID of the transactional email to send. |
email | string | Yes | The email address of the recipient. |
addToAudience | boolean | No | If true , a contact will be created in your audience using the email value (if a matching contact doesn’t already exist). |
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. |
headers | object | No | Additional headers to send with the request. |
APIError
class, which provides statusCode
and json
properties containing the API’s error response details. For implementation examples, see the Usage section.
Name | Type | Required | Notes |
---|---|---|---|
perPage | integer | No | How many results to return per page. Must be between 10 and 50. Defaults to 20 if omitted. |
cursor | string | No | A cursor, to return a specific page of results. Cursors can be found from the pagination.nextCursor value in each response. |
v5.0.1
(May 13, 2025) - Added a headers
parameter for sendEvent()
and sendTransactionalEmail()
, enabling support for the Idempotency-Key
header.v5.0.0
(Apr 29, 2025)
ValidationError
is now thrown when parameters are not added correctly.Error
is now returned if the API key is missing.v4.1.0
(Feb 27, 2025) - Support for new List transactional emails endpoint.v4.0.0
(Jan 16, 2025)
APIError
to more easily understand API errors. See usage example.getCustomFields()
method (you can now use listContactProperties()
instead).v3.4.1
(Dec 18, 2024) - Support for a new description
attribute in getMailingLists()
.v3.4.0
(Oct 29, 2024) - Added rate limit handling with RateLimitExceededError
.v3.3.0
(Sep 9, 2024) - Added testApiKey()
method.v3.2.0
(Aug 23, 2024) - Added support for a new mailingLists
attribute in findContact()
.v3.1.1
(Aug 16, 2024) - Support for a new isPublic
attribute in getMailingLists()
.v3.1.0
(Aug 12, 2024) - The SDK now accepts null
as a value for contact properties in createContact()
, updateContact()
and sendEvent()
, which allows you to reset/empty properties.v3.0.0
(Jul 2, 2024) - sendTransactionalEmail()
now accepts an object instead of separate parameters (breaking change).v2.2.0
(Jul 2, 2024) - Deprecated. Added new addToAudience
option to sendTransactionalEmail()
.v2.1.1
(Jun 20, 2024) - Added support for mailing lists in createContact()
, updateContact()
and sendEvent()
.v2.1.0
(Jun 19, 2024) - Added support for new List mailing lists endpoint.v2.0.0
(Apr 19, 2024)
userId
as a parameter to findContact()
. This includes a breaking change for the findContact()
parameters.userId
values must now be strings (could have also been numbers previously).v1.0.1
(Apr 1, 2024) - Fixed types for sendEvent()
.v1.0.0
(Mar 28, 2024) - Fix for ESM types. Switched to named export.v0.4.0
(Mar 22, 2024) - Support for new eventProperties
in sendEvent()
. This includes a breaking change for the sendEvent()
parameters.v0.3.0
(Feb 22, 2024) - Updated minimum Node version to 18.0.0.v0.2.1
(Feb 6, 2024) - Fix for ESM imports.v0.2.0
(Feb 1, 2024) - CommonJS support.v0.1.5
(Jan 25, 2024) - getCustomFields()
now returns type
values for each contact property.v0.1.4
(Jan 25, 2024) - Added support for userId
in sendEvent()
request. Added missing error response type for sendEvent()
requests.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.