# Global values API

> Workspace-wide values reused in emails, automation steps and conditions as {{global.key}}.

Base URL: `https://api.emailit.com/v2`. Authenticate with `Authorization: Bearer <API key>`.

## Create a global value — POST /global-values

> Create a workspace-wide value, such as a webinar date or a booking link, used as {{global.key}} in emails, automation steps and conditions.

# Create a global value

Creates a global value: one value for the whole workspace, used as `{{global.<key>}}` in templates, campaigns, automation emails and step settings, in conditions, and as a date to wait for. Requires an API key with the `full` scope. See [Global values](/docs/contacts/global-values/).

`POST /global-values`

## Body parameters

- `key` (string, required): Starts with a lowercase letter and uses lowercase letters, digits and `_`, up to 64 characters. Unique in the workspace.

- `name` (string): A display name, up to 191 characters.

- `type` (string): `text`, `number`, `boolean`, `date`, `datetime` or `url`.

- `value` (string | number | boolean): The value, checked against the type: a number for `number`, `true` or `false` for `boolean`, `YYYY-MM-DD` for `date`, an ISO 8601 date and time for `datetime` (stored in UTC), and an `http` or `https` URL for `url`.

- `description` (string): A note for your team, up to 1000 characters.

## Returns

Returns `201` with the [global value](#the-global-value-object) in `data`. Returns `400` with `errors` when a field is invalid, `409` when the key is taken, and `422` when the workspace has 500 global values.

**Request** `POST /global-values`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/global-values \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "webinar_date", "name": "Webinar date", "type": "datetime", "value": "2026-11-05T17:00:00Z"}'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/global-values', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"key": "webinar_date", "name": "Webinar date", "type": "datetime", "value": "2026-11-05T17:00:00Z"}),
});
const result = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/global-values",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"key": "webinar_date", "name": "Webinar date", "type": "datetime", "value": "2026-11-05T17:00:00Z"},
)
result = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('global-values', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['key' => 'webinar_date', 'name' => 'Webinar date', 'type' => 'datetime', 'value' => '2026-11-05T17:00:00Z'],
]);
$result = json_decode($response->getBody(), true);
```

## The global value object

- `object` (string): Always `global_value`.

- `id` (string): The ID (`gv_…`).

- `key` (string): The key, used as `{{global.<key>}}`.

- `name` (string | null): A display name.

- `type` (string): `text`, `number`, `boolean`, `date`, `datetime` or `url`.

- `value` (string | number | boolean | null): The value: a number for `number`, `true` or `false` for `boolean`, and a string otherwise (`YYYY-MM-DD` for `date`, ISO 8601 in UTC for `datetime`).

- `description` (string | null): A note for your team.

- `created_at` (string): When it was created.

- `updated_at` (string): When it last changed.

---
Source: https://emailit.com/docs/api-reference/global-values/create/

## Retrieve a global value — GET /global-values/{id}

> Retrieve one global value by its ID or key.

# Retrieve a global value

Returns one global value. Requires an API key with the `full` scope.

`GET /global-values/{id}`

## Path parameters

- `id` (string, required): The ID (`gv_…`) or the key.

## Returns

Returns the [global value](/docs/api-reference/global-values/create/#the-global-value-object) in `data`, or `404`.

**Request** `GET /global-values/{id}`

**cURL**

```bash
curl https://api.emailit.com/v2/global-values/webinar_date \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/global-values/webinar_date', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/global-values/webinar_date",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('global-values/webinar_date', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);
```

---
Source: https://emailit.com/docs/api-reference/global-values/get/

## Update a global value — POST /global-values/{id}

> Change a global value's value, key, name, type or description. Emails sent from then on use the new value.

# Update a global value

Changes a global value. Send only the fields to change. Requires an API key with the `full` scope.

Emails sent from then on use the new value, and so do automation runs that reach a **Wait until** step afterwards. Runs already waiting keep the date they read. Changing the key breaks `{{global.<old key>}}` in your templates.

`POST /global-values/{id}`

## Path parameters

- `id` (string, required): The ID (`gv_…`) or the key.

## Body parameters

- `key` (string): A new key, unique in the workspace.

- `name` (string | null): A display name.

- `type` (string): A new type. The current value must fit it, or send a new `value` too.

- `value` (string | number | boolean | null): The new value, checked against the type. `null` clears it.

- `description` (string | null): A note for your team.

## Returns

Returns the updated [global value](/docs/api-reference/global-values/create/#the-global-value-object) in `data`. Returns `400` when a field is invalid, `404` if it doesn't exist, and `409` when the new key is taken.

**Request** `POST /global-values/{id}`

**cURL**

```bash
curl -X POST https://api.emailit.com/v2/global-values/webinar_date \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "2026-12-03T17:00:00Z"}'
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/global-values/webinar_date', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({"value": "2026-12-03T17:00:00Z"}),
});
const result = await res.json();
```

**Python**

```python
import os, requests

r = requests.post(
    "https://api.emailit.com/v2/global-values/webinar_date",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
    json={"value": "2026-12-03T17:00:00Z"},
)
result = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->post('global-values/webinar_date', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
    'json' => ['value' => '2026-12-03T17:00:00Z'],
]);
$result = json_decode($response->getBody(), true);
```

---
Source: https://emailit.com/docs/api-reference/global-values/update/

## List global values — GET /global-values

> List all global values of the workspace, sorted by key.

# List global values

Returns every global value of the workspace, sorted by key. A workspace has at most 500, so there's no paging. Requires an API key with the `full` scope.

`GET /global-values`

## Returns

- `data` (object[]): The [global values](/docs/api-reference/global-values/create/#the-global-value-object).

**Request** `GET /global-values`

**cURL**

```bash
curl https://api.emailit.com/v2/global-values \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/global-values', {
  method: 'GET',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();
```

**Python**

```python
import os, requests

r = requests.get(
    "https://api.emailit.com/v2/global-values",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->get('global-values', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);
```

---
Source: https://emailit.com/docs/api-reference/global-values/list/

## Delete a global value — DELETE /global-values/{id}

> Delete a global value. Templates that use it render it empty.

# Delete a global value

Deletes a global value. `{{global.<key>}}` then renders empty, conditions on it see no value, and **Wait until** steps that read it take their "date passed" path. Requires an API key with the `full` scope.

`DELETE /global-values/{id}`

## Path parameters

- `id` (string, required): The ID (`gv_…`) or the key.

## Returns

Returns `{ "message": "Global value was deleted." }`, or `404`.

**Request** `DELETE /global-values/{id}`

**cURL**

```bash
curl -X DELETE https://api.emailit.com/v2/global-values/seats \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const res = await fetch('https://api.emailit.com/v2/global-values/seats', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const result = await res.json();
```

**Python**

```python
import os, requests

r = requests.delete(
    "https://api.emailit.com/v2/global-values/seats",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
result = r.json()
```

**PHP**

```php
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.emailit.com/v2/']);

$response = $client->delete('global-values/seats', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('EMAILIT_API_KEY')],
]);
$result = json_decode($response->getBody(), true);
```

---
Source: https://emailit.com/docs/api-reference/global-values/delete/