PHP SDK
The official 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:
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.
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.
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
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()
- contactProperties->create()
- contactProperties->get()
- mailingLists->get()
- events->send()
- transactional->send()
- transactional->get()
apiKey->test()
Test if your API key is valid.
Parameters
None
Example
Response
This method will return a success or error message:
contacts->create()
Create a new contact.
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
Response
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.
contacts->update()
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 | 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
Response
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.
contacts->find()
Find a contact.
Parameters
You must use one parameter in the request.
Name | Type | Required | Notes |
---|---|---|---|
$email | string | No | |
$user_id | string | No |
Examples
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.
contacts->delete()
Delete a contact.
Parameters
You must use one parameter in the request.
Name | Type | Required | Notes |
---|---|---|---|
$email | string | No | |
$user_id | string | No |
Example
Response
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.
contactProperties->create()
Create a new contact property.
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
Response
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.
contactProperties->get()
Get a list of your account’s contact properties.
Parameters
Name | Type | Required | Notes |
---|---|---|---|
$list | string | No | Use “custom” to retrieve only your account’s custom properties. |
Example
Response
This method will return a list of contact property objects containing key
, label
and type
attributes.
mailingLists->get()
Get a list of your account’s mailing lists. Read more about mailing lists
Parameters
None
Example
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.
events->send()
Send an event to trigger an email in Loops. Read more about events
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. |
Examples
Response
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.
transactional->send()
Send a transactional email to a contact. Learn about sending transactional email
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[]["content_type"] | string | No | The MIME type of the file. |
$attachments[]["data"] | string | No | The base64-encoded content of the file. |
Examples
Response
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:
transactional->get()
Get a list of published transactional emails.
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
Response
Version history
v0.1.0
(Feb 27, 2025) - Initial release.
Contributing
Bug reports and pull requests are welcome on GitHub at github.com/Loops-so/loops-rb. Please read our Contributing Guidelines.