Base URL

The Unipile API is built on REST principles. We enforce HTTPS in every request to improve data security, integrity, and privacy. The API does not support HTTP.

All requests contain the following base URL: https://api.unipile.com/v2

This URL is set by default when using SDKs.

Authentication

All requests must be authenticated using API Keys.

Set your API Key in a X-API-KEY header or when instantiating an SDK Client:

import { AccountsApi } from 'unipile';

const unipileAccounts = new AccountsApi({ apiKey: 'your-api-key' });

X-API-KEY: your-api-key

❗️
Application scoped keys
When using methods, you should use API Keys belonging to the same Application as the Account you are targeting.

Response codes

Resend uses standard HTTP codes to indicate the success or failure of your requests.

In general, 2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues.

Checkout Error responses for more informations about all error types.

Rate limiting

On Methods API, requests are rate limited at multiple levels. Learn more about Rate Limit
On Core API, endpoints does not have a rate-limit.

Pagination

Methods that return a list of results are always paginated.

Pagination method

Depending of the provider and the method, an offset or cursor value is used to request next pages:

Cursor paginated requests will return next_cursor to be sent in the subsequent request. Note that is next_cursor is null, there is no more results.
Classic paginated requests require the offset value of the next request to be incremented by the limit value of the previous one. Note that if datais an empty array, there is no more results.

Page size

The limit parameter controls the maximum number of items returned in a single page.

The default value varies depending on the provider and the endpoint. Unipile uses the same page sizes as the provider’s native applications whenever possible. For example, if Instagram loads conversation lists in batches of 20 items, the default limit is set to 20. If LinkedIn loads them in batches of 25 items, the default is set to 25.

❗️
Some providers may technically allow higher or lower values than the default. While Unipile exposes this flexibility when supported, overriding the default value is generally discouraged. The default page size is usually the one used by the provider’s own applications and therefore produces the most natural request patterns.
Unless you have a specific requirement, it is recommended to use the default limit value provided by the endpoint.

Sending Files

By default, all endpoints use the application/json content type, which requires the request body to be a JSON object. When sending files (for example, attachments in Send an Email), file content must be encoded as a base64 string to fit the JSON format.

Using application/json (base64)

Use this approach for small files. Here an example for Send an Email :

curl --request POST \
  --url https://api.unipile.com/v2/account_id/emails/send \
  --header 'accept: application/json' \
  --header "content-type: application/json" \
  --data '{
    "to": [{"email":"[email protected]"}],
    "subject": "Test email",
    "plain_text": "Hello",
    "attachments": [
      {
        "filename": "file.txt",
        "content": "SGVsbG8gd29ybGQ=",
        "content_type": "text/plain"
      }
    ]
  }'

Using multipart/form-data

For larger files (typically > 1MB), use multipart/form-data. This avoids base64 overhead and improves performance. Here an example for Send an Email :

curl --request POST \
  --url https://api.unipile.com/v2/account_id/emails/send \
  --header 'content-type: multipart/form-data' \
  --form 'to[0][email][email protected]' \
  --form 'subject=Test email' \
  --form 'plain_text=Hello' \
  --form 'attachments[0]=@PathToFile' \

Using multipart/form-data is recommended for large files to reduce payload size and improve upload efficiency.

Here the list of endpoints that support multipart:

Open API Specification

Unipile use the Open API specification. The schema is available at:

https://api.unipile.com/v2/docs/json

You can import it into an API platform like Postman using this URL.