Push API Reference

The Userlist Push API is a write-only JSON API that allows you to send data to Userlist. You can use the Push API to create and update users, companies, relationships, events, and send transactional messages. The base URL for the Push API the following:

Base URL

https://push.userlist.com

Authentication

To start sending data into Userlist, you first have to get your Push API Key from the Push Settings.

It is used to authenticate your requests to the Push API and connect the data with your account. Keep this Push API Key secure, or an attacker will be able to mess with your data and automations.

All requests to our Push API need to have the Push API Key in the Authorization header.

Authorization

1
Authorization: Push your-push-key-here

Errors

When things go wrong, the Push API will respond with appropriate HTTP status codes. Status codes in the 4xx range indicate a problem with the initial request. Status codes in the 5xx range indicate errors on the server.

The Push API will also respond with a JSON body describing the error in more detail.

1
2
3
4
5
6
7
8
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "status": 422,
  "code": "unprocessable_content",
  "errors": ["User must exist"]
}

The following table lists the most common HTTP status codes you may encounter when using the Push API:

Status	Name	Description
`401`	Unauthorized	Invalid Push key or authorization scheme
`403`	Forbidden	You’re accessing a feature that isn’t included in your plan
`404`	Not Found	The endpoint you specified was not found.
`413`	Content Too Large	The payload you provided was too large. See Limits.
`422`	Unprocessable Entity	The payload you provided was invalid. See response body for details.
`429`	Too Many Requests	You exceeded the rate limit for your account. See Limits.

Limits

The Push API has a rate limit of 1000 requests per minute per account. Additionally, there is also a 100KB request size limit.

If you exceed the rate limit, you will receive a 429 Too Many Requests response, including headers that indicate the limit, remaining requests, and reset time.

1
2
3
4
5
6
7
8
9
10
11
12
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1741873313
Retry-After: 59

{
  "status": 429,
  "code": "too_many_requests",
  "errors": ["Rate limit of 1000 requests per 60 seconds exceeded. Please try again in 59 seconds."]
}

If you exceed the request size limit, you will receive a 413 Content Too Large response.

1
2
3
4
5
6
7
8
HTTP/1.1 413 Content Too Large
Content-Type: application/json

{
  "status": 413,
  "code": "content_too_large",
  "errors": ["Payload is too large. Request was 1 MB, but the limit is 100 KB."]
}

Payloads & Responses

The Push API expects payloads as JSON and responds with JSON. It’s recommended to set the Accept and Content-Type headers accordingly.

1
2
3
POST /users HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8

Object keys, as well as event names, will be normalized to snake_case. You’re free to use any format you like for these, just be aware that we’ll store it in snake_case way.

Timestamps are expected to be strings formatted according to RFC3339/ISO8601: YYYY-MM-DDTHH:MM:SS+HH:MM. If no time zone is given, we’ll assume UTC.

Custom properties

Custom properties are key-value pairs that you can use to store additional information about users, companies, and relationships, and events. You can use any string as a key, and the value can be a string, number, boolean, array, object, or null.

We will normalize all keys to snake_case internally. Strings formatted according to RFC3339/ISO8601 will automatically be recognized as timestamps.

Nested properties will help structure your data, especially if you’re managing multiple products in one Userlist account.

E.g. a billing plan property for Product A will look like this: user.product_a.billing_plan.

1
2
3
4
5
6
7
8
9
10
11
{
  "identifier": "3d70d1d4-484a-4e72-8857-916ee525214e",
  "properties": {
    "product_a": {
      "billing_plan": "pro"
    },
    "product_b": {
      "billing_plan": "free"
    }
  }
}

Referencing and embedding resources

In all payload that allow referencing another resources by their identifier (like an event that references the user that performed the event) it’s also possible to embed the resource in place.

The following example shows a payload that references a user by their identifier.

1
2
3
{
  "user": "3d70d1d4-484a-4e72-8857-916ee525214e"
}

This is equivalent to the following expanded payload.

1
2
3
4
5
{
  "user": {
    "identifier": "3d70d1d4-484a-4e72-8857-916ee525214e"
  }
}

This allows complex updates of multiple related resources in the same transaction. The following example shows how to update a nested user resource within the parent payload.

1
2
3
4
5
6
7
8
9
10
{
  "user": {
    "identifier": "3d70d1d4-484a-4e72-8857-916ee525214e",
    "email": "user-123@example.com",
    "properties": {
      "first_name": "Delaney",
      "last_name": "Jones"
    }
  }
}

Users

Users are people who interact with your product, or sign up for your marketing emails.

Create or Update a User

Creates a new user or updates an existing one. If the user already exists, the user will be updated partially with only the specified data. Omitted/unspecified data will remain unchanged. Remove a value by setting it to null.

Request


      POST
      /users

Properties

identifier Required unless email is provided string number

The unique identifier of the user.
email Required unless identifier is provided string

The email address of the user.
signed_up_at Optional string

The timestamp when the user signed up formatted as YYYY-MM-DDTHH:MM:SS+HH:MM (RFC3339/ISO8601).
properties Optional object

Custom properties for the user. See Custom properties for more details.
relationships Optional array

Array of relationships to companies. See Relationships for more details.
company Optional string number object

A single company that the user is related to. This is a shortcut to creating just a single relationship. See Companies for more details.
companies Optional array

An array of companies that the user is related to. This is a shortcut to creating multiple relationships without any properties. See Companies for more details.
preferences Optional array

Array of subscription preferences for the user. Only the included preferences will be updated, all others will retain the current values. See Subscription Preferences for more details.
Hide nested properties Show nested properties
- topic Required string
  
  The identifier of the topic. You can find the topic identifier in the Topics settings of your account.
- subscribed Required boolean
  
  The user’s subscription preference for the topic.

Response

Status	Description
`202`	The request was accepted and will be processed soon. There is no response body.
`422`	There was a validation error with your payload. See Errors for details about the response body.

Examples

POST /users

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
POST /users HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{
  "identifier": "user-123",
  "email": "user-123@example.com",
  "properties": {
    "first_name": "Delaney",
    "last_name": "Jones"
  },
  "relationships": [
    {
      "company": "company-567",
      "properties": { "role": "owner" }
    }
  ],
  "preferences": [
    { "topic": "topic-890", "subscribed": false }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
curl -X POST "https://push.userlist.com/users" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "identifier": "user-123",
  "email": "user-123@example.com",
  "properties": {
    "first_name": "Delaney",
    "last_name": "Jones"
  },
  "relationships": [
    {
      "company": "company-567",
      "properties": { "role": "owner" }
    }
  ],
  "preferences": [
    { "topic": "topic-890", "subscribed": false }
  ]
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.users.create({
  "identifier": "user-123",
  "email": "user-123@example.com",
  "properties": {
    "first_name": "Delaney",
    "last_name": "Jones"
  },
  "relationships": [
    {
      "company": "company-567",
      "properties": { "role": "owner" }
    }
  ],
  "preferences": [
    { "topic": "topic-890", "subscribed": false }
  ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
require 'userlist'

Userlist::Push.configure do |config|
  config.push_key = 'your-push-key-here'
end

Userlist::Push.users.push({
  identifier: "user-123",
  email: "user-123@example.com",
  properties: { first_name: "Delaney", last_name: "Jones" },
  relationships: [
    {
      company: "company-567",
      properties: { role: "owner" }
    }
  ],
  preferences: [ { topic: "topic-890", subscribed: false } ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$userlist = new \Userlist\Push(['push_key' => 'your-push-key-here']);

$userlist->users->push([
  "identifier" => "user-123",
  "email" => "user-123@example.com",
  "properties" => [
    "first_name" => "Delaney",
    "last_name" => "Jones"
  ],
  "relationships" => [
    [
      "company" => "company-567",
      "properties" => [ "role" => "owner" ]
    ]
  ],
  "preferences" => [
    [ "topic" => "topic-890", "subscribed" => false ]
  ]
])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from userlist import Userlist

userlist = Userlist(push_key='your-push-key-here')

userlist.users.push({
  'identifier': 'user-123',
  'email': 'user-123@example.com',
  'properties': {
    'first_name': 'Delaney',
    'last_name': 'Jones'
  },
  'relationships': [
    {
      'company': 'company-567',
      'properties': { 'role': 'owner' }
    }
  ],
  'preferences': [
    { 'topic': 'topic-890', 'subscribed': false }
  ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
url = "https://push.userlist.com/users"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{
  "identifier" => "user-123",
  "email" => "user-123@example.com",
  "properties" => %{
    "first_name" => "Delaney",
    "last_name" => "Jones"
  },
  "relationships" => [
    %{
      "company" => "company-567",
      "properties" => %{ "role" => "owner" }
    }
  ],
  "preferences" => [
    %{ "topic" => "topic-890", "subscribed" => false }
  ]
}

HTTPoison.post(url, Jason.encode!(payload), headers)

Delete a User

Deletes the specified user from the system. If the user does not exist, the request will be ignored.

Request


      DELETE
      /users

Properties

identifier Required unless email is provided string number

The unique identifier of the user.
email Required unless identifier is provided string

The email address of the user.

Response

Status	Description
`202`	The request was accepted and will be processed soon. There is no response body.
`422`	There was a validation error with your payload. See Errors for details about the response body.

Examples

DELETE /users

1
2
3
4
5
6
7
8
9
10
DELETE /users HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{
  "identifier": "user-123",
  "email": "user-123@example.com"
}

1
2
3
4
5
6
7
8
curl -X DELETE "https://push.userlist.com/users" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "identifier": "user-123",
  "email": "user-123@example.com"
}'

1
2
3
4
5
6
7
8
9
10
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.users.delete({
  "identifier": "user-123",
  "email": "user-123@example.com"
})

1
2
3
4
5
6
7
require 'userlist'

Userlist::Push.configure do |config|
  config.push_key = 'your-push-key-here'
end

Userlist::Push.users.delete({ identifier: "user-123", email: "user-123@example.com" })

1
2
3
4
5
6
7
8
9
10
11
12
13
14
url = "https://push.userlist.com/users"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{
  "identifier" => "user-123",
  "email" => "user-123@example.com"
}

HTTPoison.delete(url, Jason.encode!(payload), headers)

Companies

Companies are organizations that your users belong to.

Create or Update a Company

Creates a new company or updates an existing one. If the company already exists, the company will be updated partially with only the specified data. Omitted/unspecified data will remain unchanged. Remove a value by setting it to null.

Request


      POST
      /companies

Properties

identifier Required string number

The unique identifier of the company.
name Optional string

The name of the company.
signed_up_at Optional string

The timestamp when the company signed up formatted as YYYY-MM-DDTHH:MM:SS+HH:MM (RFC3339/ISO8601).
properties Optional object

Custom properties for the company. See Custom properties for more details.
relationships Optional array

Array of relationships to users. See Relationships for more details.
user Optional string number object

A single user that the company is related to. This is a shortcut to creating just a single relationship. See Users for more details.
users Optional array

An array of user identifiers that the company is related to. This is a shortcut to creating multiple relationships without any properties. See Users for more details.

Response

Status	Description
`202`	The request was accepted and will be processed soon. There is no response body.
`422`	There was a validation error with your payload. See Errors for details about the response body.

Examples

POST /companies

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
POST /companies HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{
  "identifier": "company-567",
  "name": "Example, Inc.",
  "properties": {
    "industry": "Software",
    "billing_plan": "enterprise"
  },
  "relationships": [
    {
      "user": {
        "identifier": "user-123",
        "email": "user-123@example.com",
        "properties": {
          "first_name": "Delaney",
          "last_name": "Jones"
        }
      },
      "properties": { "role": "owner" }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
curl -X POST "https://push.userlist.com/companies" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "identifier": "company-567",
  "name": "Example, Inc.",
  "properties": {
    "industry": "Software",
    "billing_plan": "enterprise"
  },
  "relationships": [
    {
      "user": {
        "identifier": "user-123",
        "email": "user-123@example.com",
        "properties": {
          "first_name": "Delaney",
          "last_name": "Jones"
        }
      },
      "properties": { "role": "owner" }
    }
  ]
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.companies.create({
  "identifier": "company-567",
  "name": "Example, Inc.",
  "properties": {
    "industry": "Software",
    "billing_plan": "enterprise"
  },
  "relationships": [
    {
      "user": {
        "identifier": "user-123",
        "email": "user-123@example.com",
        "properties": {
          "first_name": "Delaney",
          "last_name": "Jones"
        }
      },
      "properties": { "role": "owner" }
    }
  ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
require 'userlist'

Userlist::Push.configure do |config|
  config.push_key = 'your-push-key-here'
end

Userlist::Push.companies.push({
  identifier: "company-567",
  name: "Example, Inc.",
  properties: {
    industry: "Software",
    billing_plan: "enterprise"
  },
  relationships: [
    {
      user: {
        identifier: "user-123",
        email: "user-123@example.com",
        properties: {
          first_name: "Delaney",
          last_name: "Jones"
        }
      },
      properties: { role: "owner" }
    }
  ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
$userlist = new \Userlist\Push(['push_key' => 'your-push-key-here']);

$userlist->companies->push([
  "identifier" => "company-567",
  "name" => "Example, Inc.",
  "properties" => [
    "industry" => "Software",
    "billing_plan" => "enterprise"
  ],
  "relationships" => [
    [
      "user" => [
        "identifier" => "user-123",
        "email" => "user-123@example.com",
        "properties" => [
          "first_name" => "Delaney",
          "last_name" => "Jones"
        ]
      ],
      "properties" => [ "role" => "owner" ]
    ]
  ]
])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
from userlist import Userlist

userlist = Userlist(push_key='your-push-key-here')

userlist.companies.push({
  'identifier': 'company-567',
  'name': 'Example, Inc.',
  'properties': {
    'industry': 'Software',
    'billing_plan': 'enterprise'
  },
  'relationships': [
    {
      'user': {
        'identifier': 'user-123',
        'email': 'user-123@example.com',
        'properties': {
          'first_name': 'Delaney',
          'last_name': 'Jones'
        }
      },
      'properties': { 'role': 'owner' }
    }
  ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
url = "https://push.userlist.com/companies"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{
  "identifier" => "company-567",
  "name" => "Example, Inc.",
  "properties" => %{
    "industry" => "Software",
    "billing_plan" => "enterprise"
  },
  "relationships" => [
    %{
      "user" => %{
        "identifier" => "user-123",
        "email" => "user-123@example.com",
        "properties" => %{
          "first_name" => "Delaney",
          "last_name" => "Jones"
        }
      },
      "properties" => %{ "role" => "owner" }
    }
  ]
}

HTTPoison.post(url, Jason.encode!(payload), headers)

Delete a Company

Deletes the specified company from the system. If the company does not exist, the request will be ignored.

Request


      DELETE
      /companies

Properties

identifier Required string number

The unique identifier of the company.

Response

Status	Description
`202`	The request was accepted and will be processed soon. There is no response body.
`422`	There was a validation error with your payload. See Errors for details about the response body.

Examples

DELETE /companies

1
2
3
4
5
6
7
DELETE /companies HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{ "identifier": "company-123" }

1
2
3
4
5
curl -X DELETE "https://push.userlist.com/companies" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "identifier": "company-123" }'

1
2
3
4
5
6
7
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.companies.delete({ "identifier": "company-123" })

1
2
3
4
5
6
7
8
9
10
11
url = "https://push.userlist.com/companies"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{ "identifier" => "company-123" }

HTTPoison.delete(url, Jason.encode!(payload), headers)

Relationships

Relationships are connections between users and companies. They can have custom properties that describe the relationship.

Create or Update a Relationship

Creates a new relationship or updates an existing one. If the relationship already exists, the relationship will be updated partially with only the specified data. Omitted/unspecified data will remain unchanged. Remove a value by setting it to null.

Request


      POST
      /relationships

Properties

user Required string number object

The identifier of the user or an embedded user object. See Users for more details.
company Required string number object

The identifier of the company or an embedded company object. See Companies for more details.
properties Optional object

Custom properties for the relationship. See Custom properties for more details.

Response

Status	Description
`202`	The request was accepted and will be processed soon. There is no response body.
`422`	There was a validation error with your payload. See Errors for details about the response body.

Examples

POST /relationships

1
2
3
4
5
6
7
8
9
10
11
POST /relationships HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{
  "user": "user-123",
  "company": "company-567",
  "properties": { "role": "admin" }
}

1
2
3
4
5
6
7
8
9
curl -X POST "https://push.userlist.com/relationships" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "user": "user-123",
  "company": "company-567",
  "properties": { "role": "admin" }
}'

1
2
3
4
5
6
7
8
9
10
11
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.relationships.create({
  "user": "user-123",
  "company": "company-567",
  "properties": { "role": "admin" }
})

1
2
3
4
5
6
7
8
9
10
11
require 'userlist'

Userlist::Push.configure do |config|
  config.push_key = 'your-push-key-here'
end

Userlist::Push.relationships.push({
  user: "user-123",
  company: "company-567",
  properties: { role: "admin" }
})

1
2
3
4
5
6
7
$userlist = new \Userlist\Push(['push_key' => 'your-push-key-here']);

$userlist->relationships->push([
  "user" => "user-123",
  "company" => "company-567",
  "properties" => [ "role" => "admin" ]
])

1
2
3
4
5
6
7
8
9
from userlist import Userlist

userlist = Userlist(push_key='your-push-key-here')

userlist.relationships.push({
  'user': 'user-123',
  'company': 'company-567',
  'properties': { 'role': 'admin' }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
url = "https://push.userlist.com/relationships"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{
  "user" => "user-123",
  "company" => "company-567",
  "properties" => %{ "role" => "admin" }
}

HTTPoison.post(url, Jason.encode!(payload), headers)

Delete a Relationship

Deletes the specified relationship from the system. If the relationship does not exist, the request will be ignored.

Request


      DELETE
      /relationships

Properties

user Required string number object

The identifier of the user or an embedded user object. See Users for more details.
company Required string number object

The identifier of the company or an embedded company object. See Companies for more details.

Response

Status	Description
`202`	The request was accepted and will be processed soon. There is no response body.
`422`	There was a validation error with your payload. See Errors for details about the response body.

Examples

DELETE /relationships

1
2
3
4
5
6
7
DELETE /relationships HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{ "user": "user-123", "company": "company-567" }

1
2
3
4
5
curl -X DELETE "https://push.userlist.com/relationships" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "user": "user-123", "company": "company-567" }'

1
2
3
4
5
6
7
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.relationships.delete({ "user": "user-123", "company": "company-567" })

1
2
3
4
5
6
7
require 'userlist'

Userlist::Push.configure do |config|
  config.push_key = 'your-push-key-here'
end

Userlist::Push.relationships.delete({ user: "user-123", company: "company-567" })

1
2
3
4
5
6
7
8
9
10
11
url = "https://push.userlist.com/relationships"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{ "user" => "user-123", "company" => "company-567" }

HTTPoison.delete(url, Jason.encode!(payload), headers)

Events

Events are actions that users or companies take in your product. Events can also be associated with both a user and a company for cases where a user performs an action within the context of a company.

Create an Event

Creates a new event in the system.

Request


      POST
      /events

Properties

name Required string

The name of the event.
user Required unless a company is provided string number object

The identifier of the user or an embedded user object that the event is associated with. See Users for more details.
company Required unless a user is provided string number object

The identifier of the company or an embedded company object that the event is associated with. See Companies for more details.
occurred_at Optional string

The timestamp when the event occurred formatted as YYYY-MM-DDTHH:MM:SS+HH:MM (RFC3339/ISO8601).
properties Optional object

Custom properties for the event. See Custom properties for more details.

Response

Status	Description
`202`	The request was accepted and will be processed soon. There is no response body.
`422`	There was a validation error with your payload. See Errors for details about the response body.

Examples

POST /events

1
2
3
4
5
6
7
8
9
10
11
12
POST /events HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{
  "name": "project_created",
  "user": "user-123",
  "company": "company-567",
  "properties": { "project_name": "New Project" }
}

1
2
3
4
5
6
7
8
9
10
curl -X POST "https://push.userlist.com/events" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "name": "project_created",
  "user": "user-123",
  "company": "company-567",
  "properties": { "project_name": "New Project" }
}'

1
2
3
4
5
6
7
8
9
10
11
12
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.events.create({
  "name": "project_created",
  "user": "user-123",
  "company": "company-567",
  "properties": { "project_name": "New Project" }
})

1
2
3
4
5
6
7
8
9
10
11
12
require 'userlist'

Userlist::Push.configure do |config|
  config.push_key = 'your-push-key-here'
end

Userlist::Push.events.push({
  name: "project_created",
  user: "user-123",
  company: "company-567",
  properties: { project_name: "New Project" }
})

1
2
3
4
5
6
7
8
$userlist = new \Userlist\Push(['push_key' => 'your-push-key-here']);

$userlist->events->push([
  "name" => "project_created",
  "user" => "user-123",
  "company" => "company-567",
  "properties" => [ "project_name" => "New Project" ]
])

1
2
3
4
5
6
7
8
9
10
from userlist import Userlist

userlist = Userlist(push_key='your-push-key-here')

userlist.events.push({
  'name': 'project_created',
  'user': 'user-123',
  'company': 'company-567',
  'properties': { 'project_name': 'New Project' }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
url = "https://push.userlist.com/events"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{
  "name" => "project_created",
  "user" => "user-123",
  "company" => "company-567",
  "properties" => %{ "project_name" => "New Project" }
}

HTTPoison.post(url, Jason.encode!(payload), headers)

Transactional Messages

Transactional messages allow you to send one-off messages to users. You can either use a predefined template or compose custom messages by providing subject and body content.

Send a Message

Sends a message to a user. You can either use a template or provide custom content. When using a template, only the template identifier is required along with the recipient. For custom messages, you must provide subject, body, and channel.

Request


      POST
      /messages

Properties

template Required unless subject and body are provided string

The identifier of the transactional message template to use. When provided, subject, body, and channel are not required as they will be taken from the template.
user Required, unless to is provided string number object

The identifier of the user or an embedded user object that should receive this message. For email messages, either user or to is required. For web messages, user is required and to must not be provided. See Users for more details.
company Optional string number object

The identifier of the company or an embedded company object that this message is associated with. See Companies for more details.
properties Optional object

Custom properties for the message. Properties are accessible in the {{event}} object in Liquid (for example {{event.project_name}}). See Custom properties for more details.

Hide additional properties Show additional properties

channel Optional string

The delivery channel for the message. Must be either email or web. Defaults to email.
to Optional string

The email address to send the message to. For email messages, either user or to is required. For web messages, this field must not be provided. Must be a valid email address.
from Optional string

The email address to send the message from. Must be a valid email address. Only applicable for email messages.
reply_to Optional string

The email address for replies. Must be a valid email address. Only applicable for email messages.
subject Optional string

The subject line of the message. Required when not using a template. Supports Liquid templating.
preheader Optional string

The preheader text for email messages. Supports Liquid templating. Only applicable for email messages.
body Optional object

The body content of the message. Required when not using a template. Supports Liquid templating and document formatting.
Hide nested properties Show nested properties
- type Required string
  
  The type of the content. Must be either html, text, or multipart.
- content Required string array
  
  The actual content of the message. For html and text, this should be a string. For multipart, this should be an array of objects with type and content properties.
sender Optional string

The identifier of the sender to use for this message. Must reference a valid sender configured in your account. If none is provided, the sender of the template will be used, or the default sender of the account if no template is specified.
theme Optional string boolean

The identifier of the theme to apply to this message. Must reference a valid theme configured in your account. If none is provided, the theme of the template will be used, or the default theme of the account if no template is specified. To fully disable theming, set the property to false.
topic Optional string

The identifier of the topic this message belongs to. Must reference a valid topic configured in your account. If none is provided, the topic of the template will be used, or the default topic of the account if no template is specified.

Response

Status	Description
`202`	The request was accepted and will be processed soon. There is no response body.
`422`	There was a validation error with your payload. See Errors for details about the response body.

Examples

POST /messages Templated Message

1
2
3
4
5
6
7
8
9
10
11
POST /messages HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{
  "template": "8e433865-bcd3-45ee-b775-983df0e4dc0f",
  "user": "user-123",
  "properties": { "project_name": "New Project" }
}

1
2
3
4
5
6
7
8
9
curl -X POST "https://push.userlist.com/messages" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "template": "8e433865-bcd3-45ee-b775-983df0e4dc0f",
  "user": "user-123",
  "properties": { "project_name": "New Project" }
}'

1
2
3
4
5
6
7
8
9
10
11
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.messages.create({
  "template": "8e433865-bcd3-45ee-b775-983df0e4dc0f",
  "user": "user-123",
  "properties": { "project_name": "New Project" }
})

1
2
3
4
5
6
7
8
9
10
11
require 'userlist'

Userlist::Push.configure do |config|
  config.push_key = 'your-push-key-here'
end

Userlist::Push.messages.push({
  template: "8e433865-bcd3-45ee-b775-983df0e4dc0f",
  user: "user-123",
  properties: { project_name: "New Project" }
})

1
2
3
4
5
6
7
$userlist = new \Userlist\Push(['push_key' => 'your-push-key-here']);

$userlist->messages->push([
  "template" => "8e433865-bcd3-45ee-b775-983df0e4dc0f",
  "user" => "user-123",
  "properties" => [ "project_name" => "New Project" ]
])

1
2
3
4
5
6
7
8
9
from userlist import Userlist

userlist = Userlist(push_key='your-push-key-here')

userlist.messages.push({
  'template': '8e433865-bcd3-45ee-b775-983df0e4dc0f',
  'user': 'user-123',
  'properties': { 'project_name': 'New Project' }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
url = "https://push.userlist.com/messages"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{
  "template" => "8e433865-bcd3-45ee-b775-983df0e4dc0f",
  "user" => "user-123",
  "properties" => %{ "project_name" => "New Project" }
}

HTTPoison.post(url, Jason.encode!(payload), headers)

POST /messages Custom Message

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
POST /messages HTTP/1.1
Host: push.userlist.com
Authorization: Push your-push-key-here
Accept: application/json
Content-Type: application/json; charset=utf-8

{
  "sender": "8b9c554c-58a0-47e8-b3e1-da1fde10348d",
  "topic": "dbf53dab-7be5-454e-a0a9-f31c31f04731",
  "to": "jane@example.com",
  "subject": "Welcome to Userlist!",
  "preheader": "Get started with Userlist",
  "body": {
    "type": "multipart",
    "content": [
      {
        "type": "html",
        "content": "<h1>Hello Jane!</h1><p>Welcome to Userlist. We're glad to have you on board!</p>"
      },
      {
        "type": "text",
        "content": "Hello Jane! Welcome to Userlist. We're glad to have you on board!"
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
curl -X POST "https://push.userlist.com/messages" \
  -H "Authorization: Push your-push-key-here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "sender": "8b9c554c-58a0-47e8-b3e1-da1fde10348d",
  "topic": "dbf53dab-7be5-454e-a0a9-f31c31f04731",
  "to": "jane@example.com",
  "subject": "Welcome to Userlist!",
  "preheader": "Get started with Userlist",
  "body": {
    "type": "multipart",
    "content": [
      {
        "type": "html",
        "content": "<h1>Hello Jane!</h1><p>Welcome to Userlist. We're glad to have you on board!</p>"
      },
      {
        "type": "text",
        "content": "Hello Jane! Welcome to Userlist. We're glad to have you on board!"
      }
    ]
  }
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import Userlist from '@userlist/push';

// This example is intended for server-side usage.
// Don't expose your push key in the browser.
const userlist = new Userlist({ pushKey: 'your-push-key-here' });

userlist.messages.create({
  "sender": "8b9c554c-58a0-47e8-b3e1-da1fde10348d",
  "topic": "dbf53dab-7be5-454e-a0a9-f31c31f04731",
  "to": "jane@example.com",
  "subject": "Welcome to Userlist!",
  "preheader": "Get started with Userlist",
  "body": {
    "type": "multipart",
    "content": [
      {
        "type": "html",
        "content": "<h1>Hello Jane!</h1><p>Welcome to Userlist. We're glad to have you on board!</p>"
      },
      {
        "type": "text",
        "content": "Hello Jane! Welcome to Userlist. We're glad to have you on board!"
      }
    ]
  }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
require 'userlist'

Userlist::Push.configure do |config|
  config.push_key = 'your-push-key-here'
end

Userlist::Push.messages.push({
  sender: "8b9c554c-58a0-47e8-b3e1-da1fde10348d",
  topic: "dbf53dab-7be5-454e-a0a9-f31c31f04731",
  to: "jane@example.com",
  subject: "Welcome to Userlist!",
  preheader: "Get started with Userlist",
  body: {
    type: "multipart",
    content: [
      {
        type: "html",
        content: "<h1>Hello Jane!</h1><p>Welcome to Userlist. We're glad to have you on board!</p>"
      },
      {
        type: "text",
        content: "Hello Jane! Welcome to Userlist. We're glad to have you on board!"
      }
    ]
  }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$userlist = new \Userlist\Push(['push_key' => 'your-push-key-here']);

$userlist->messages->push([
  "sender" => "8b9c554c-58a0-47e8-b3e1-da1fde10348d",
  "topic" => "dbf53dab-7be5-454e-a0a9-f31c31f04731",
  "to" => "jane@example.com",
  "subject" => "Welcome to Userlist!",
  "preheader" => "Get started with Userlist",
  "body" => [
    "type" => "multipart",
    "content" => [
      [
        "type" => "html",
        "content" => "<h1>Hello Jane!</h1><p>Welcome to Userlist. We're glad to have you on board!</p>"
      ],
      [
        "type" => "text",
        "content" => "Hello Jane! Welcome to Userlist. We're glad to have you on board!"
      ]
    ]
  ]
])

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
from userlist import Userlist

userlist = Userlist(push_key='your-push-key-here')

userlist.messages.push({
  'sender': '8b9c554c-58a0-47e8-b3e1-da1fde10348d',
  'topic': 'dbf53dab-7be5-454e-a0a9-f31c31f04731',
  'to': 'jane@example.com',
  'subject': 'Welcome to Userlist!',
  'preheader': 'Get started with Userlist',
  'body': {
    'type': 'multipart',
    'content': [
      {
        'type': 'html',
        'content': '<h1>Hello Jane!</h1><p>Welcome to Userlist. We're glad to have you on board!</p>'
      },
      {
        'type': 'text',
        'content': 'Hello Jane! Welcome to Userlist. We're glad to have you on board!'
      }
    ]
  }
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
url = "https://push.userlist.com/messages"

headers = [
  {"Authorization", "Push your-push-key-here"},
  {"Content-Type", "application/json; charset=utf-8"},
  {"Accept", "application/json"}
]

payload = %{
  "sender" => "8b9c554c-58a0-47e8-b3e1-da1fde10348d",
  "topic" => "dbf53dab-7be5-454e-a0a9-f31c31f04731",
  "to" => "jane@example.com",
  "subject" => "Welcome to Userlist!",
  "preheader" => "Get started with Userlist",
  "body" => %{
    "type" => "multipart",
    "content" => [
      %{
        "type" => "html",
        "content" => "<h1>Hello Jane!</h1><p>Welcome to Userlist. We're glad to have you on board!</p>"
      },
      %{
        "type" => "text",
        "content" => "Hello Jane! Welcome to Userlist. We're glad to have you on board!"
      }
    ]
  }
}

HTTPoison.post(url, Jason.encode!(payload), headers)

Authentication

Errors

Limits

Payloads & Responses

Custom properties

Referencing and embedding resources

Users

Create or Update a User

Request

Properties

identifier Required unless email is provided string number

email Required unless identifier is provided string

signed_up_at Optional string

properties Optional object

relationships Optional array

company Optional string number object

companies Optional array

preferences Optional array

topic Required string

subscribed Required boolean

Response

Examples

Delete a User

Request

Properties

identifier Required unless email is provided string number

email Required unless identifier is provided string

Response

Examples

Companies

Create or Update a Company

Request

Properties

identifier Required string number

name Optional string

signed_up_at Optional string

properties Optional object

relationships Optional array

user Optional string number object

users Optional array

Response

Examples

Delete a Company

Request

Properties

identifier Required string number

Response

Examples

Relationships

Create or Update a Relationship

Request

Properties

user Required string number object

company Required string number object

properties Optional object

Response

Examples

Delete a Relationship

Request

Properties

user Required string number object

company Required string number object

Response

Examples

Events

Create an Event

Request

Properties

name Required string

user Required unless a company is provided string number object

company Required unless a user is provided string number object

occurred_at Optional string

properties Optional object

Response

Examples

Transactional Messages

Send a Message

Request

Properties

template Required unless subject and body are provided string