Loops PHP Package

Introduction

This is the official PHP package for Loops, an email platform for modern software companies.

Installation

Install the Loops package using Composer:

composer require loops-so/loops

Requires PHP 8.1.

Usage

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, in an environment variable).

See the API documentation to learn more about rate limiting and error handling.

To use the package, first initialise the client with your API key, then you can call one of the methods.

API rate limits can be handled with the included RateLimitExceededError exception.

use Loops\LoopsClient;

$loops = new LoopsClient(env('LOOPS_API_KEY'));

// Test API key
$result = $loops->apiKey->test();

// Create a contact and catch errors
try {
    $result = $loops->contacts->create('user@example.com', [
      'firstName' => 'John'
    ]);
} catch (Loops\Exceptions\APIError $e) {
    // Handle API errors (400, 401, 403, etc)
    echo $e->getMessage();
    $returnedJson = $e->getJson(); // JSON returned by the API
    $statusCode = $e->getStatusCode(); // HTTP status code from the response
} catch (\Exception $e) {
    // Handle any other unexpected errors
    echo "Unexpected error: " . $e->getMessage();
}

Handling rate limits

You can use the check for rate limit issues with your requests.

You can access details about the rate limits from the getLimit and getRemaining functions.

try {
    $result = $loops->contacts->create('user@example.com', [
      'firstName' => 'John'
    ]);
} catch (Loops\Exceptions\RateLimitExceededError $e) {
    // Handle rate limiting
    echo "Rate limit hit. Limit: " . $e->getLimit() . ", requests remaining: " . $e->getRemaining();
} catch (Loops\Exceptions\APIError $e) {
    // Handle API errors (400, 401, 403, etc)
    echo $e->getMessage();
} catch (\Exception $e) {
    // Handle any other unexpected errors
    echo "Unexpected error: " . $e->getMessage();
}

Default contact properties

Each contact in Loops has a set of default properties. These will always be returned in API results.

id
email
firstName
lastName
source
subscribed
userGroup
userId
optInStatus

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

apiKey->test()
contacts->create()
contacts->update()
contacts->find()
contacts->delete()
contacts->checkSuppression()
contacts->removeSuppression()
contactProperties->create()
contactProperties->list()
mailingLists->list()
events->send()
transactional->send()
transactional->list()
transactional->create()
transactional->get()
transactional->update()
transactional->ensureDraft()
transactional->publish()
dedicatedSendingIps->list()
themes->list()
themes->get()
components->list()
components->get()
campaigns->list()
campaigns->create()
campaigns->get()
campaigns->update()
campaignGroups->list()
campaignGroups->create()
campaignGroups->get()
campaignGroups->update()
audienceSegments->list()
audienceSegments->get()
workflows->list()
workflows->get()
workflows->getNode()
emailMessages->get()
emailMessages->update()
emailMessages->preview()
transactionalGroups->list()
transactionalGroups->create()
transactionalGroups->get()
transactionalGroups->update()
uploads->upload()

apiKey->test()

Test if your API key is valid.

API Reference

Parameters

None

Example

$result = $loops->apiKey->test();

Response

This method will return a success or error message:

{
  "success": true,
  "teamName": "Company name"
}

{
  "error": "Invalid API key"
}

contacts->create()

Create a new contact.

API Reference

Parameters

Name	Type	Required	Notes
`$email`	string	Yes	If a contact already exists with this email address, an `APIError` will be thrown.
`$properties`	array	No	An array 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).
`$mailing_lists`	array	No	An array of mailing list IDs and boolean subscription statuses.

Examples

$result = $loops->contacts->create("hello@gmail.com");

$contact_properties = [
  'firstName' => "Bob" /* Default property */,
  'favoriteColor' => "Red" /* Custom property */,
];
$mailing_lists = [
  'cm06f5v0e45nf0ml5754o9cix' => TRUE,
  'cm16k73gq014h0mmj5b6jdi9r' => FALSE,
];
$result = $loops->contacts->create(
  email: "hello@gmail.com",
  properties: $contact_properties,
  mailing_lists: $mailing_lists
);

Response

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

Error handling is done through the APIError class, which provides getStatusCode() and getJson() methods for retrieving the API's error response details. For implementation examples, see the Usage section.

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

contacts->update()

Update a contact.

Note: To update a contact's email address, the contact requires a $user_id value. Then you can make a request with their $user_id and an updated email address.

API Reference

Parameters

Name	Type	Required	Notes
`$email`	string	No	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. Required if `$user_id` is not present.
`$user_id`	string	No	The contact's unique user ID. If you use `$user_id` without `$email`, this value must have already been added to your contact in Loops. Required if `$email` is not present.
`$properties`	array	No	An array 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).
`$mailing_lists`	array	No	An array of mailing list IDs and boolean subscription statuses.

Example

$result = $loops->contacts->update(
  email: 'hello@gmail.com',
  properties: [
    'firstName' => 'Bob', /* Default property */
    'favoriteColor' => 'Blue' /* Custom property */
  ]
);

// Updating a contact's email address using $user_id
$result = $loops->contacts->update(
  user_id: '1234',
  email: 'newemail@gmail.com'
);

// Subscribe a contact to a mailing list
$result = $loops->contacts->update(
  email: 'hello@gmail.com',
  mailing_lists: [
    'cm06f5v0e45nf0ml5754o9cix' => true /* Subscribe */,
    'cm16k73gq014h0mmj5b6jdi9r' => false /* Unsubscribe */
  ]
);

Response

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

Error handling is done through the APIError class, which provides getStatusCode() and getJson() methods for retrieving the API's error response details. For implementation examples, see the Usage section.

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

contacts->find()

Find a contact.

API Reference

Parameters

You must use one parameter in the request.

Name	Type	Required	Notes
`$email`	string	No
`$user_id`	string	No

Examples

$result = $loops->contacts->find(email: 'hello@gmail.com');

$result = $loops->contacts->find(user_id: '12345');

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": "hello@gmail.com",
    "firstName": "Bob",
    "lastName": null,
    "source": "API",
    "subscribed": true,
    "userGroup": "",
    "userId": "12345",
    "mailingLists": {
      "cm06f5v0e45nf0ml5754o9cix": true
    },
    "optInStatus": null,
    "favoriteColor": "Blue" /* Custom property */
  }
]

contacts->delete()

Delete a contact.

API Reference

Parameters

You must use one parameter in the request.

Name	Type	Required	Notes
`$email`	string	No
`$user_id`	string	No

Example

$result = $loops->contacts->delete(email: 'hello@gmail.com')

$result = $loops->contacts->delete(user_id: '12345')

Response

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

Error handling is done through the APIError class, which provides getStatusCode() and getJson() methods for retrieving the API's error response details. For implementation examples, see the Usage section.

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

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

contacts->checkSuppression()

Check if a contact is currently suppressed.

API Reference

Parameters

You must use one parameter in the request.

Name	Type	Required	Notes
`$email`	string	No
`$user_id`	string	No

Example

$result = $loops->contacts->checkSuppression(email: 'hello@gmail.com');

$result = $loops->contacts->checkSuppression(user_id: '12345');

Response

{
  "contact": {
    "id": "cll6b3i8901a9jx0oyktl2m4u",
    "email": "adam@loops.so",
    "userId": null
  },
  "isSuppressed": true,
  "removalQuota": {
    "limit": 100,
    "remaining": 10
  }
}

Error handling is done through the APIError class, which provides getStatusCode() and getJson() methods for retrieving the API's error response details. For implementation examples, see the Usage section.

// HTTP 400 Bad Request
{
  "success": false,
  "message": "An email or userId is required."
}

// HTTP 404 Not Found
{
  "success": false,
  "message": "This contact was not found."
}

contacts->removeSuppression()

Remove suppression for a contact.

API Reference

Parameters

You must use one parameter in the request.

Name	Type	Required	Notes
`$email`	string	No
`$user_id`	string	No

Example

$result = $loops->contacts->removeSuppression(email: 'hello@gmail.com');

$result = $loops->contacts->removeSuppression(user_id: '12345');

Response

{
  "success": true,
  "message": "Email removed from suppression list.",
  "removalQuota": {
    "limit": 100,
    "remaining": 4
  }
}

Error handling is done through the APIError class, which provides getStatusCode() and getJson() methods for retrieving the API's error response details. For implementation examples, see the Usage section.

// HTTP 400 Bad Request
{
  "success": false,
  "message": "This contact is not suppressed."
}

// HTTP 404 Not Found
{
  "success": false,
  "message": "This contact was not found."
}

contactProperties->create()

Create a new contact property.

API Reference

Parameters

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

Examples

$result = $loops->contactProperties->create("planName", "string");

Response

{
  "success": true
}

Error handling is done through the APIError class, which provides getStatusCode() and getJson() methods for retrieving the API's error response details. For implementation examples, see the Usage section.

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

contactProperties->list()

Get a list of your account's contact properties.

API Reference

Parameters

Name	Type	Required	Notes
`$list`	string	No	Use "custom" to retrieve only your account's custom properties.

Example

$result = $loops->contactProperties->list();

$result = $loops->contactProperties->list(list: "custom");

Response

This method will return a list of contact property objects containing key, label and type attributes.

[
  {
    "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"
  }
]

mailingLists->list()

Get a list of your account's mailing lists. Read more about mailing lists

API Reference

Parameters

None

Example

$result = $loops->mailingLists->list();

Response

This method will return a list of mailing list objects containing id, name, description and isPublic attributes.

If your account has no mailing lists, an empty list will be returned.

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

events->send()

Send an event to trigger an email in Loops. Read more about events

API Reference

Parameters

Name	Type	Required	Notes
`$event_name`	string	Yes
`$email`	string	No	The contact's email address. Required if `$user_id` is not present.
`$user_id`	string	No	The contact's unique user ID. If you use `$user_id` without `$email`, this value must have already been added to your contact in Loops. Required if `$email` is not present.
`$contact_properties`	array	No	An array 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).
`$event_properties`	array	No	An array 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).
`$mailing_lists`	array	No	An array of mailing list IDs and boolean subscription statuses.
`$headers`	array	No	Additional headers to send with the request.

Examples

$result = $loops->events->send(
  event_name: 'signup',
  email: 'hello@gmail.com'
);

$result = $loops->events->send(
  event_name: 'signup',
  email: 'hello@gmail.com',
  event_properties: [
    'username' => 'user1234',
    'signupDate' => '2024-03-21T10:09:23Z'
  ],
  mailing_lists: [
    'cm06f5v0e45nf0ml5754o9cix' => true,
    'cm16k73gq014h0mmj5b6jdi9r' => false
  ]
;

# In this case with both email and user_id present, the system will look for a contact with either a
#  matching `email` or `user_id` value.
# If a contact is found for one of the values (e.g. `email`), the other value (e.g. `user_id`) will be updated.
# If a contact is not found, a new contact will be created using both `email` and `user_id` values.
# Any values added in `contact_properties` will also be updated on the contact.
$result = $loops->events->send(
  event_name: 'signup',
  email: 'hello@gmail.com',
  user_id: '1234567890',
  contact_properties: [
    'firstName' => 'Bob',
    'plan' => 'pro',
  }]
});

# Example with Idempotency-Key header
$result = $loops->events->send(
  event_name: 'signup',
  email: 'hello@gmail.com',
  headers: [
    'Idempotency-Key' => '550e8400-e29b-41d4-a716-446655440000'
  ]
);

Response

{
  "success": true
}

Error handling is done through the APIError class, which provides getStatusCode() and getJson() methods for retrieving the API's error response details. For implementation examples, see the Usage section.

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

transactional->send()

Send a transactional email to a contact. Learn about sending transactional email

API Reference

Parameters

Name	Type	Required	Notes
`$transactional_id`	string	Yes	The ID of the transactional email to send.
`$email`	string	Yes	The email address of the recipient.
`$add_to_audience`	boolean	No	If `true`, a contact will be created in your audience using the `$email` value (if a matching contact doesn’t already exist).
`$data_variables`	array	No	An array containing data as defined by the data variables added to the transactional email template. Values can be of type `string` or `number`.
`$attachments`	array[]	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`	array	No	Additional headers to send with the request.

Examples

$result = $loops->transactional->send(
  transactional_id: 'clfq6dinn000yl70fgwwyp82l',
  email: 'hello@gmail.com',
  data_variables: [
    'loginUrl' => 'https://myapp.com/login/',
  ]
);

# Example with Idempotency-Key header
$result = $loops->transactional->send(
  transactional_id: 'clfq6dinn000yl70fgwwyp82l',
  email: 'hello@gmail.com',
  data_variables: [
    'loginUrl' => 'https://myapp.com/login/',
  ],
  headers: [
    'Idempotency-Key' => '550e8400-e29b-41d4-a716-446655440000'
  ]
);

# Please contact us to enable attachments on your account.
$result = $loops->transactional->send(
  transactional_id: 'clfq6dinn000yl70fgwwyp82l',
  email: 'hello@gmail.com',
  data_variables: [
    'loginUrl' => 'https://myapp.com/login/',
  ],
  attachments: [
    [
      'filename' => 'presentation.pdf',
      'contentType' => 'application/pdf',
      'data' => base64_encode(file_get_contents('path/to/presentation.pdf'))
    ]
  ]
);

Response

{
  "success": true
}

Error handling is done through the APIError class, which provides getStatusCode() and getJson() methods for retrieving the API's error response details. For implementation examples, see the Usage section.

If there is a problem with the request, a descriptive error message will be returned:

// 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"
}

transactional->list()

Get a paginated list of transactional emails, most recently created first.

API Reference

Parameters

Name	Type	Required	Notes
`$per_page`	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.

Example

$result = $loops->transactional->list();

$result = $loops->transactional->list(per_page: 15);

Response

{
  "pagination": {
    "totalResults": 23,
    "returnedResults": 20,
    "perPage": 20,
    "totalPages": 2,
    "nextCursor": "clyo0q4wo01p59fsecyxqsh38",
    "nextPage": "https://app.loops.so/api/v1/transactional-emails?cursor=clyo0q4wo01p59fsecyxqsh38&perPage=20"
  },
  "data": [
    {
      "id": "clfn0k1yg001imo0fdeqg30i8",
      "name": "Welcome email",
      "draftEmailMessageId": null,
      "publishedEmailMessageId": "cly8k3m0n0044jpx2bghepq45",
      "createdAt": "2023-11-06T17:48:07.249Z",
      "updatedAt": "2023-11-06T17:48:07.249Z",
      "dataVariables": []
    },
    {
      "id": "cll42l54f20i1la0lfooe3z12",
      "name": "Password reset",
      "draftEmailMessageId": "cla3r8s9t0422ua56iqovab01",
      "publishedEmailMessageId": "clb4s9t0u0533vb67jrpwbc12",
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-02-02T02:56:28.845Z",
      "dataVariables": [
        "confirmationUrl"
      ]
    },
    {
      "id": "clw6rbuwp01rmeiyndm80155l",
      "name": "Team invite",
      "draftEmailMessageId": "clc5t0u1v0644wc78ksqxcd23",
      "publishedEmailMessageId": null,
      "createdAt": "2024-05-14T19:02:52.000Z",
      "updatedAt": "2024-05-14T19:02:52.000Z",
      "dataVariables": [
        "firstName",
        "lastName",
        "inviteLink"
      ]
    },
    ...
  ]
}

transactional->create()

Create a new transactional email. An empty draft email message is created automatically.

API Reference

Parameters

Name	Type	Required	Notes
`$name`	string	Yes	The name of the transactional email.
`$transactional_group_id`	string	No	The ID of the group to add this transactional email to. Defaults to the team's default group when omitted.

Example

$result = $loops->transactional->create(name: 'Welcome email');

Response

{
  "id": "clfq6dinn000yl70fgwwyp82l",
  "name": "Welcome email",
  "draftEmailMessageId": "cly8k3m0n0044jpx2bghepq45",
  "draftEmailMessageContentRevisionId": "clm9n4o6p0088lrz4dijslt67",
  "publishedEmailMessageId": null,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z",
  "dataVariables": []
}

transactional->get()

Get a single transactional email by ID.

API Reference

Parameters

Name	Type	Required	Notes
`$transactional_id`	string	Yes	The ID of the transactional email.

Example

$result = $loops->transactional->get(transactional_id: 'clfq6dinn000yl70fgwwyp82l');

transactional->update()

Update a transactional email.

At least one field alongside transactional_id must be provided.

API Reference

Parameters

Name	Type	Required	Notes
`$transactional_id`	string	Yes	The ID of the transactional email.
`$name`	string	No	The updated name.
`$transactional_group_id`	string	No	The ID of the group to move this transactional email to.

Example

$result = $loops->transactional->update(
  transactional_id: 'clfq6dinn000yl70fgwwyp82l',
  name: 'Updated welcome email'
);

transactional->ensureDraft()

Ensure a transactional email has a draft email message. If a draft already exists it is returned unchanged; otherwise a new empty draft is created.

API Reference

Parameters

Name	Type	Required	Notes
`$transactional_id`	string	Yes	The ID of the transactional email.

Example

$result = $loops->transactional->ensureDraft(transactional_id: 'clfq6dinn000yl70fgwwyp82l');

transactional->publish()

Publish the transactional email's current draft email message.

API Reference

Parameters

Name	Type	Required	Notes
`$transactional_id`	string	Yes	The ID of the transactional email.

Example

$result = $loops->transactional->publish(transactional_id: 'clfq6dinn000yl70fgwwyp82l');

uploads->upload()

Upload an image asset for use in LMX email content. The returned finalUrl can be used in an <Image> tag in your LMX content.

API Reference

Parameters

Name	Type	Required	Notes
`$path`	string	Yes	Path to an image file. Supported types: JPEG, PNG, GIF, and WebP. Maximum file size is 4,000,000 bytes (4 MB).

Example

$result = $loops->uploads->upload(path: '/path/to/image.png');

$imageUrl = $result['finalUrl'];

Response

{
  "emailAssetId": "clu1v4w6x0254tz42lrcwat45",
  "finalUrl": "https://cdn.example.com/image.png"
}

dedicatedSendingIps->list()

Get a list of Loops' dedicated sending IP addresses.

API Reference

Parameters

None

Example

$result = $loops->dedicatedSendingIps->list();

Response

["1.2.3.4", "5.6.7.8"]

themes->list()

List email themes.

API Reference

Parameters

Name	Type	Required	Notes
`$per_page`	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.

Example

$result = $loops->themes->list();

$result = $loops->themes->list(per_page: 15, cursor: 'clyo0q4wo01p59fsecyxqsh38');

themes->get()

Get a single email theme by ID.

API Reference

Parameters

Name	Type	Required	Notes
`$theme_id`	string	Yes	The ID of the theme.

Example

$result = $loops->themes->get(theme_id: 'clo5p8q0r0132ntx6flkunw89');

components->list()

List email components.

API Reference

Parameters

Name	Type	Required	Notes
`$per_page`	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.

Example

$result = $loops->components->list();

components->get()

Get a single email component by ID.

API Reference

Parameters

Name	Type	Required	Notes
`$component_id`	string	Yes	The ID of the component.

Example

$result = $loops->components->get(component_id: 'clp6q9r1s0154ouy7gmlovx90');

campaigns->list()

List campaigns.

API Reference

Parameters

Name	Type	Required	Notes
`$per_page`	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.

Example

$result = $loops->campaigns->list();

campaigns->create()

Create a new draft campaign.

API Reference

Parameters

Name	Type	Required	Notes
`$name`	string	Yes	The campaign name.
`$campaign_group_id`	string	No	The ID of the group to add this campaign to.
`$mailing_list_id`	string	No	The ID of the mailing list to send to.
`$audience_segment_id`	string	No	The ID of an audience segment. Setting this clears any `audience_filter`.
`$audience_filter`	array	No	A tree of audience conditions. See the API reference for the filter schema.
`$scheduling`	array	No	When the campaign should send. Use `['method' => 'now']` or `['method' => 'schedule', 'timestamp' => '...']`.

Example

$result = $loops->campaigns->create(name: 'Spring announcement');

$result = $loops->campaigns->create(
  name: 'Spring announcement',
  mailing_list_id: 'cm06f5v0e45nf0ml5754o9cix',
  scheduling: ['method' => 'schedule', 'timestamp' => '2026-06-01T10:00:00Z']
);

Response

{
  "success": true,
  "campaignId": "cln4o7p9q0110msw5ekjtmv78",
  "name": "Spring announcement",
  "status": "Draft",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z",
  "emailMessageId": "cly8k3m0n0044jpx2bghepq45",
  "emailMessageContentRevisionId": "clm9n4o6p0088lrz4dijslt67"
}

campaigns->get()

Get a single campaign by ID.

API Reference

Parameters

Name	Type	Required	Notes
`$campaign_id`	string	Yes	The ID of the campaign.

Example

$result = $loops->campaigns->get(campaign_id: 'cln4o7p9q0110msw5ekjtmv78');

campaigns->update()

Update a draft campaign's name, group, audience, or scheduling.

At least one field alongside campaign_id must be provided.

API Reference

Parameters

Name	Type	Required	Notes
`$campaign_id`	string	Yes	The ID of the campaign.
`$name`	string	No	The updated name.
`$campaign_group_id`	string	No	The ID of the group to move this campaign to.
`$scheduling`	array	No	When the campaign should send. Use `['method' => 'now']` or `['method' => 'schedule', 'timestamp' => '...']`.
`$mailing_list_id`	string	No	The ID of the mailing list to send to. Pass `null` to clear.
`$audience_segment_id`	string	No	The ID of an audience segment. Setting this clears any `audience_filter`. Pass `null` to clear.
`$audience_filter`	array	No	A tree of audience conditions. See the API reference for the filter schema. Pass `null` to clear.

Example

$result = $loops->campaigns->update(
  campaign_id: 'cln4o7p9q0110msw5ekjtmv78',
  name: 'Updated name'
);

// Clear the mailing list audience target
$result = $loops->campaigns->update(
  campaign_id: 'cln4o7p9q0110msw5ekjtmv78',
  mailing_list_id: null
);

campaignGroups->list()

List campaign groups.

API Reference

Parameters

Name	Type	Required	Notes
`$per_page`	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.

Example

$result = $loops->campaignGroups->list();

campaignGroups->create()

Create a campaign group.

API Reference

Parameters

Name	Type	Required	Notes
`$name`	string	Yes	Cannot be the reserved name "Unsorted".
`$description`	string	No	An optional description for the group.

Example

$result = $loops->campaignGroups->create(name: 'Newsletters', description: 'Monthly updates');

campaignGroups->get()

Get a campaign group by ID.

API Reference

Parameters

Name	Type	Required	Notes
`$campaign_group_id`	string	Yes	The ID of the campaign group.

Example

$result = $loops->campaignGroups->get(campaign_group_id: 'clq7r0s2t0176pvz8hnmpwy01');

campaignGroups->update()

Update a campaign group's name or description.

At least one field alongside campaign_group_id must be provided.

API Reference

Parameters

Name	Type	Required	Notes
`$campaign_group_id`	string	Yes	The ID of the campaign group.
`$name`	string	No	Cannot be the reserved name "Unsorted".
`$description`	string	No

Example

$result = $loops->campaignGroups->update(
  campaign_group_id: 'clq7r0s2t0176pvz8hnmpwy01',
  name: 'Updated name'
);

audienceSegments->list()

List audience segments.

API Reference

Parameters

Name	Type	Required	Notes
`$per_page`	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.

Example

$result = $loops->audienceSegments->list();

audienceSegments->get()

Get an audience segment by ID.

API Reference

Parameters

Name	Type	Required	Notes
`$audience_segment_id`	string	Yes	The ID of the audience segment.

Example

$result = $loops->audienceSegments->get(audience_segment_id: 'clr8s1t3u0198qw09iotqzx12');

workflows->list()

List workflows.

API Reference

Parameters

Name	Type	Required	Notes
`$per_page`	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.

Example

$result = $loops->workflows->list();

workflows->get()

Get a simplified workflow graph.

API Reference

Parameters

Name	Type	Required	Notes
`$workflow_id`	string	Yes	The ID of the workflow.

Example

$result = $loops->workflows->get(workflow_id: 'cls9t2u4v0210rx20jpuary23');

workflows->getNode()

Get detailed data for a single workflow node.

API Reference

Parameters

Name	Type	Required	Notes
`$workflow_id`	string	Yes	The ID of the workflow.
`$node_id`	string	Yes	The ID of the workflow node.

Example

$result = $loops->workflows->getNode(
  workflow_id: 'cls9t2u4v0210rx20jpuary23',
  node_id: 'clt0u3v5w0232sy31kqvbzs34'
);

emailMessages->get()

Get an email message, including its compiled LMX content.

API Reference

Parameters

Name	Type	Required	Notes
`$email_message_id`	string	Yes	The ID of the email message.

Example

$result = $loops->emailMessages->get(email_message_id: 'cly8k3m0n0044jpx2bghepq45');

emailMessages->update()

Update an email message.

At least one field alongside email_message_id must be provided.

API Reference

Parameters

Name	Type	Required	Notes
`$email_message_id`	string	Yes	The ID of the email message.
`$expected_revision_id`	string	No	Supply a value matching the current `contentRevisionId` to avoid 409 conflicts.
`$subject`	string	No	The email subject line.
`$preview_text`	string	No	The email preview text.
`$from_name`	string	No	The sender name.
`$from_email`	string	No	The sender email address (the name before the `@`; your sending domain will be automatically appended).
`$reply_to_email`	string	No	The reply-to email address.
`$lmx`	string	No	The LMX content for the email message.
`$contact_properties_fallbacks`	array	No	Contact property fallback values. Pass `null` as a value to remove an individual fallback entry.
`$event_properties_fallbacks`	array	No	Event property fallback values. Pass `null` as a value to remove an individual fallback entry.
`$data_variables_fallbacks`	array	No	Data variable fallback values. Pass `null` as a value to remove an individual fallback entry.

Example

$result = $loops->emailMessages->update(
  email_message_id: 'cly8k3m0n0044jpx2bghepq45',
  expected_revision_id: 'clm9n4o6p0088lrz4dijslt67',
  subject: 'Updated subject',
  lmx: '<Email><Text>Hello</Text></Email>'
);

// Example with contact property fallbacks
$result = $loops->emailMessages->update(
  email_message_id: 'cly8k3m0n0044jpx2bghepq45',
  contact_properties_fallbacks: [
    'firstName' => 'there',      // If firstName is missing, use "there"
    'company' => 'your company', // If company is missing, use "your company"
    'planName' => null           // null removes the fallback for "planName"
  ]
);

emailMessages->preview()

Send a test preview of an email message to one or more addresses.

API Reference

Parameters

Name	Type	Required	Notes
`$email_message_id`	string	Yes	The ID of the email message.
`$emails`	array	Yes	One or more addresses to send the preview to.
`$contact_properties`	array	No	Contact property values to render. Accepted for campaign and workflow previews.
`$event_properties`	array	No	Event property values to render. Accepted for workflow previews only.
`$data_variables`	array	No	Transactional data variables to render. Accepted for transactional previews only.

Example

$result = $loops->emailMessages->preview(
  email_message_id: 'cly8k3m0n0044jpx2bghepq45',
  emails: ['test@example.com'],
  contact_properties: ['firstName' => 'Alex']
);

transactionalGroups->list()

List transactional groups.

API Reference

Parameters

Name	Type	Required	Notes
`$per_page`	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.

Example

$result = $loops->transactionalGroups->list();

transactionalGroups->create()

Create a transactional group.

API Reference

Parameters

Name	Type	Required	Notes
`$name`	string	Yes	Cannot be the reserved name "Unsorted".
`$description`	string	No	An optional description for the group.

Example

$result = $loops->transactionalGroups->create(name: 'Account emails');

transactionalGroups->get()

Get a transactional group by ID.

API Reference

Parameters

Name	Type	Required	Notes
`$transactional_group_id`	string	Yes	The ID of the transactional group.

Example

$result = $loops->transactionalGroups->get(transactional_group_id: 'clv2w3x4y0288xbb0kqrsuv67');

transactionalGroups->update()

Update a transactional group's name or description.

At least one field alongside transactional_group_id must be provided.

API Reference

Parameters

Name	Type	Required	Notes
`$transactional_group_id`	string	Yes	The ID of the transactional group.
`$name`	string	No	Cannot be the reserved name "Unsorted".
`$description`	string	No

Example

$result = $loops->transactionalGroups->update(
  transactional_group_id: 'clv2w3x4y0288xbb0kqrsuv67',
  name: 'Updated name'
);

Testing

vendor/bin/phpunit

Contributing

Bug reports and pull requests are welcome. Please read our Contributing Guidelines.

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.github		.github
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.txt		LICENSE.txt
README.md		README.md
composer.json		composer.json
composer.phar		composer.phar
phpunit.xml		phpunit.xml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Loops PHP Package

Introduction

Installation

Usage

Handling rate limits

Default contact properties

Custom contact properties

Methods

apiKey->test()

Parameters

Example

Response

contacts->create()

Parameters

Examples

Response

contacts->update()

Parameters

Example

Response

contacts->find()

Parameters

Examples

Response

contacts->delete()

Parameters

Example

Response

contacts->checkSuppression()

Parameters

Example

Response

contacts->removeSuppression()

Parameters

Example

Response

contactProperties->create()

Parameters

Examples

Response

contactProperties->list()

Parameters

Example

Response

mailingLists->list()

Parameters

Example

Response

events->send()

Parameters

Examples

Response

transactional->send()

Parameters

Examples

Response

transactional->list()

Parameters

Example

Response

transactional->create()

Parameters

Example

Response

transactional->get()

Parameters

Example

transactional->update()

Parameters

Example

transactional->ensureDraft()

Parameters

Example

transactional->publish()

Parameters