API reference

Apps and keys

An app has two environments (sandbox, production). API keys are created and revoked here, with the portal session.

Create an app (with its sandbox and production environments)#

POST/apps

Authentication: Portal session (Bearer ses_…)

Request body (JSON)

Field	Type		Description
`name`	string	required	Name shown in the console (2 to 80 characters). Unique per app within your account.

Example

bash

curl -X POST "$INBOX_API/apps" \
  -H "Authorization: Bearer $INBOX_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My CRM"
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/apps`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_SESSION}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "My CRM"
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/apps",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_SESSION']}",
    },
    json={
        "name": "My CRM",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/apps');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_SESSION'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'My CRM',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 201 Created

{
  "id": "8b2717b6-be9e-42c7-8889-6e3c6ea4cbe3",
  "name": "My CRM",
  "createdAt": "2026-11-12T08:33:45.324Z",
  "environments": [
    {
      "id": "7d3d2aa8-d312-48d7-894c-25b906dfa11a",
      "kind": "sandbox"
    },
    {
      "id": "badd0f25-05da-4716-8c28-f2fe1baba427",
      "kind": "production"
    }
  ]
}

List the account's apps#

GET/apps

Authentication: Portal session (Bearer ses_…)

Example

bash

curl "$INBOX_API/apps" \
  -H "Authorization: Bearer $INBOX_SESSION"

javascript

const res = await fetch(`${process.env.INBOX_API}/apps`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_SESSION}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/apps",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_SESSION']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/apps');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_SESSION'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

[
  {
    "id": "8b2717b6-be9e-42c7-8889-6e3c6ea4cbe3",
    "name": "My CRM",
    "createdAt": "2026-11-12T08:33:45.324Z",
    "environments": [
      {
        "id": "7d3d2aa8-d312-48d7-894c-25b906dfa11a",
        "kind": "sandbox"
      },
      {
        "id": "badd0f25-05da-4716-8c28-f2fe1baba427",
        "kind": "production"
      }
    ]
  }
]

Generate an API key. The secret is shown only once.#

POST/apps/{appId}/keys

Authentication: Portal session (Bearer ses_…)

Parameters

Name	Location	Type	Description
`appId`required	path	string	App ID.

Request body (JSON)

Field	Type		Description
`name`	string	required	Name shown in the console (2 to 80 characters). Unique per app within your account.
`environment`	string	required	Key environment: `sandbox` for testing, `production` for sending to real recipients.Values: sandbox, production
`scopes`	string[]	required	Scopes of the key. A key can only do what it has been granted. Values: messages:send, messages:read, templates:manage, webhooks:manage, connections:read, connections:manage, usage:read.Values: messages:send, messages:read, templates:manage, webhooks:manage, connections:read, connections:manage, usage:read

Example

bash

curl -X POST "$INBOX_API/apps/APP_ID/keys" \
  -H "Authorization: Bearer $INBOX_SESSION" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local dev",
    "environment": "sandbox",
    "scopes": [
      "messages:send",
      "messages:read",
      "connections:manage",
      "connections:read",
      "templates:manage",
      "webhooks:manage",
      "usage:read"
    ]
  }'

javascript

const res = await fetch(`${process.env.INBOX_API}/apps/APP_ID/keys`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_SESSION}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Local dev",
    "environment": "sandbox",
    "scopes": [
      "messages:send",
      "messages:read",
      "connections:manage",
      "connections:read",
      "templates:manage",
      "webhooks:manage",
      "usage:read"
    ]
  }),
});
const data = await res.json();

python

import os
import requests

res = requests.post(
    f"{os.environ['INBOX_API']}/apps/APP_ID/keys",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_SESSION']}",
    },
    json={
        "name": "Local dev",
        "environment": "sandbox",
        "scopes": [
            "messages:send",
            "messages:read",
            "connections:manage",
            "connections:read",
            "templates:manage",
            "webhooks:manage",
            "usage:read",
        ],
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/apps/APP_ID/keys');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_SESSION'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Local dev',
        'environment' => 'sandbox',
        'scopes' => [
            'messages:send',
            'messages:read',
            'connections:manage',
            'connections:read',
            'templates:manage',
            'webhooks:manage',
            'usage:read',
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Response · 201 Created

{
  "id": "5ef37bc9-8aac-43ef-81b1-6bb3bdb66e78",
  "name": "Local dev",
  "prefix": "pk_test_bwcA3X-A",
  "environment": "sandbox",
  "scopes": [
    "messages:send",
    "messages:read",
    "connections:manage",
    "connections:read",
    "templates:manage",
    "webhooks:manage",
    "usage:read"
  ],
  "lastUsedAt": null,
  "revokedAt": null,
  "createdAt": "2026-11-12T08:33:45.382Z",
  "secret": "pk_test_26f602c48c47ef280792fd3a506473688df70b80118"
}

List an app's keys (without the secret)#

GET/apps/{appId}/keys

Authentication: Portal session (Bearer ses_…)

Parameters

Name	Location	Type	Description
`appId`required	path	string	App ID.

Example

bash

curl "$INBOX_API/apps/APP_ID/keys" \
  -H "Authorization: Bearer $INBOX_SESSION"

javascript

const res = await fetch(`${process.env.INBOX_API}/apps/APP_ID/keys`, {
  headers: {
    Authorization: `Bearer ${process.env.INBOX_SESSION}`,
  },
});
const data = await res.json();

python

import os
import requests

res = requests.get(
    f"{os.environ['INBOX_API']}/apps/APP_ID/keys",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_SESSION']}",
    },
)
print(res.json())

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/apps/APP_ID/keys');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_SESSION'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Response · 200 OK

[
  {
    "id": "5ef37bc9-8aac-43ef-81b1-6bb3bdb66e78",
    "name": "Local dev",
    "prefix": "pk_test_bwcA3X-A",
    "environment": "sandbox",
    "scopes": [
      "messages:send",
      "messages:read",
      "connections:manage",
      "connections:read",
      "templates:manage",
      "webhooks:manage",
      "usage:read"
    ],
    "lastUsedAt": null,
    "revokedAt": null,
    "createdAt": "2026-11-12T08:33:45.382Z"
  }
]

Revoke an API key#

DELETE/apps/{appId}/keys/{keyId}

Authentication: Portal session (Bearer ses_…)

Parameters

Name	Location	Type	Description
`keyId`required	path	string	API key ID.

Example

bash

curl -X DELETE "$INBOX_API/apps/APP_ID/keys/KEY_ID" \
  -H "Authorization: Bearer $INBOX_SESSION"

javascript

const res = await fetch(`${process.env.INBOX_API}/apps/APP_ID/keys/KEY_ID`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_SESSION}`,
  },
});
const data = res.status;

python

import os
import requests

res = requests.delete(
    f"{os.environ['INBOX_API']}/apps/APP_ID/keys/KEY_ID",
    headers={
        "Authorization": f"Bearer {os.environ['INBOX_SESSION']}",
    },
)
print(res.status_code)

php

<?php

$ch = curl_init(getenv('INBOX_API') . '/apps/APP_ID/keys/KEY_ID');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('INBOX_SESSION'),
    ],
]);
curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE);

Response · 204 No Content

(no content)