SocketLabs API Documentation

The SocketLabs API allows you to access SocketLabs features programmatically via HTTP calls without having to log into our Control Panel, allowing you to automate common tasks. Please check back frequently, as we are working hard to add more features. Endpoints may be modified or removed while development is ongoing. # Getting Started: Create an API Key For Complex Sender and Simple Sender, regardless of version, an API key must be created on the [API Key Management](https://portal.socketlabs.com/x/smtp-api/key-manager) page in your SocketLabs account. Be sure to choose the \`SocketLabs Api\` API Access option so your API key will have the correct access. It is important to keep your API key secure because it can be used to modify features for your SocketLabs account. ## Authentication All calls to the SocketLabs API are authenticated using the API key that you generated. Authenticate your calls to the SocketLabs API using the `Authorization` header with the `Bearer` authentication scheme. ### Example Bearer authorization header: `Authorization: Bearer YOUR-API-KEY` If your application or system does not support the `Bearer` authentication scheme, you may also use the `Basic` scheme. If using the `Basic` scheme, you may use any string as the username and then your API key as the password. More information about `Basic` authentication can be found [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization#Directives). ### Example Basic authorization header: `Authorization: Basic YOUR-API-KEY` - [Injection API](https://docs.socketlabs.com/#00166e83-9e84-47f8-86cd-724be3f01acb) - [Event Webhooks](https://docs.socketlabs.com/#998247dc-aba7-4662-980c-0e84e9d706a4) - [Suppression API](https://docs.socketlabs.com/#1ffb945c-1b3a-4cfb-a4b2-32e0275f3936) - [Reporting API](https://docs.socketlabs.com/#86ef1dc8-a956-41d7-a8ca-4d7391377e26) - [Marketing API](https://docs.socketlabs.com/#cf807626-5084-4ee1-b04d-f4bce9f3f81d) - [Changelog](https://docs.socketlabs.com/#b586312a-328e-4889-8485-e39df5fe352e) # Pagination Every endpoint that returns an array of results includes offset pagination. Pagination is defined by an order (\`sortDirection\`), a limit (\`pageSize\`), and an offset (\`pageNumber\`) from the start. ## **Query parameters** | **Name** | **Type** | **Description** | | --- | --- | --- | | pageSize | number | The number of items to return. Default max size (100) if not specified, min size (1). **NOTE**: Csv file download endpoints have a default max size of (500000) | | pageNumber | number | The (zero-based) page number of items from the start of the query to skip. A zero-based page number 0 is the start value. | | sortDirection | `asc`, `dsc` | The direction the array is sorted | | sortField | string | the property name the array is sorted by. | | startDate | dateTime | The start date in yyyy-mm-dd HH:MM:SS format | | endDate | dateTime | The end date in yyyy-mm-dd HH:MM:SS format | | filters | string | Narrow down the results based on specific search criteria. See the Filters section below for details. | # Filters Add filters to the query string to narrow down the results based on specific criteria. The format for adding filters is `filters=field=predicate:value`, where `field` is the name of the field in the dataset on which to apply the filter, `predicate` is the type of comparison to perform on the field, and `value` is the value against which the field should be compared. ## Supported Predicates ### String | Predicate Key | Description | Example | | --- | --- | --- | | `eq` | Is Equal To | `name=eq:test` | | `neq` | Not Equal To | `name=neq:test` | | `like` | Contains | `name=like:some` | | `nlike` | Does Not Contain | `name=nlike:some` | | `start` | Starts With | `name=start:test` | | `end` | Ends With | `name=end:ing` | ### Number | Predicate Key | Description | Example | | --- | --- | --- | | `eq` | Is Equal To | `id=eq:12` | | `neq` | Not Equal To | `id=neq:12` | | `gt` | Greater Than | `score=gt:60` | | `lt` | Less Than | `score=lt:80` | | `gte` | Before/Greater Than and Equal To | `score=gte:60` | | `lte` | After/Less Than and Equal To | `score=lte:80` | ### Date | Predicate Key | Description | Example | | --- | --- | --- | | `eq` | Is Equal To | `created=eq:2022-02-28` | | `gt` | Before/Greater Than | `created=gt:2022-02-01` | | `lt` | After/Less Than | `created=lt:2022-03-01` | | `gte` | Greater Than and Equal To | `created=gte:2022-02-01` | | `lte` | Less Than and Equal To | `created=lte:2022-03-01` | ### Boolean | Predicate Key | Description | Example | | --- | --- | --- | | `eq` | Is Equal To | `isActive=eq:true` | | `neq` | Not Equal To | `isActive=neq:true` | ### Enum | Predicate Key | Description | Example | | --- | --- | --- | | `eq` | Is Equal To | `status=eq:active` | | `neq` | Not Equal To | `status=neq:active` | ### Combining Filters You can combile multiple filters by separating them with an `&` Example: `filters=name=start:jo&emailAddress=end:gmail.com` ### Example ``` https://api.socketlabs.com/v1/servers/12345/search/?filters=status=eq:active&isActive=eq:true ``` # Date Formats When filtering by date, three date formats (Each a subset of [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)) are supported. The following date formats may be used: ``` yyyy-MM-ddTHH:mm:ssK yyyy-MM-ddK yyyy-MM-dd ``` By default, all dates will be in UTC time. If you need to specify a local time offset, you can do by adding or subracting the local offset (`K` property) to your timestamp. For more information on how to use time offsets, please see [this Wikipedia article](https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC). ### Date Limits Data returned by the SocketLabs API is limited to the dates allowed by the Detailed Reporting History date range for your SocketLabs plan. If you attempt to search a date range that is not allowed by your current plan, an error will be returned. To find out what your current limits are, or to upgrade to a plan with more limits, please navigate to [your plans page](https://cp.socketlabs.com/servers/x/plan/upgrade#/). # **Response** The response type will include the `data` property containing the array of results and the `total` property containing the total number of results available. **NOTE**: All csv file download endpoints include a Content-Range header. This header specifies units, start, end & total. (ex: rows 0-99/187). Additionally these endpoints will respond with a HTTP Status code of 206 (Partial Content) for all requested pages except the final page which will return a status code of 200 (Ok). | | **Type** | **Description** | | --- | --- | --- | | data | array | The array of results | | total | number | The number of results in total | ### Example ``` json { "data": [ … ], "total": 123 } ``` # Error Handling Sometimes there will be errors with your API call. This could be due to any number of issues such as incorrect syntax, validation errors, limits being exceeded, or something going wrong on our server. When this happens the HTTP response will contain an error code, with additional information provided in the response body. The body can contain either a single error or a list of errors. ## Example error: ``` json { "error" : [ { "errorType": "InvalidDomainFormat", "message": "Domain name not formatted correctly." } ] } ``` ## API Error Model | **Property Name** | **Data Type** | | --- | --- | | message | string | | errorType | string | # Rate Limiting All requests against the SocketLabs Api are limited to 100 requests within 60 seconds. Requests made in excess to this limit will result in an error. There are some endpoints whos rate limiting differs from the standard, which are shown below: | **Endpoint** | **Rate Limit** | | --- | --- | | \*/reports/message\* | 30 requests/60 seconds |