Skip to main content

API quickstart

This guide shows the shortest path from creating an API key to making a request against the Better Email API.

1. Create an API key​

Organization admins can create API keys from Better Email:

  1. Open Settings.
  2. Go to API Keys.
  3. Create a new API key.
  4. Copy the key when it is shown and store it securely.

TODO: Add a screenshot of the API Keys settings page showing the create-key flow and one-time key display.

The full key is only meant for server-side systems that you control. Do not paste it into frontend code, public repositories, shared screenshots, or support tickets.

2. Store the key​

Store the API key as an environment variable in the system that will call Better Email:

export BETTER_EMAIL_API_KEY="your_api_key_here"

Use your own secret-management system in production.

3. Make a request​

List the recipient fields available to your organization:

curl https://app.better.email/api/v1/recipient_fields \
  -H "Authorization: Bearer $BETTER_EMAIL_API_KEY" \
  -H "Accept: application/json"

A successful response returns a JSON object with a recipient_fields array:

{
  "recipient_fields": [
    {
      "id": 123,
      "name": "First name",
      "key": "first_name",
      "data_type": "text",
      "insertable": true,
      "source": "api",
      "integration_id": null,
      "esp_field_name": null,
      "custom_insertion_code": null,
      "created_at": "2026-05-04T09:00:00.000Z",
      "updated_at": "2026-05-04T09:00:00.000Z"
    }
  ]
}

4. Create an API-managed field​

curl https://app.better.email/api/v1/recipient_fields \
  -X POST \
  -H "Authorization: Bearer $BETTER_EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "recipient_field": {
      "name": "Loyalty score",
      "key": "loyalty_score",
      "data_type": "number",
      "insertable": true
    }
  }'

Better Email marks fields created this way with source: api. API-managed fields can be updated and deleted through the API. Manual fields and fields synced from ESP integrations can be listed and read through the API, but cannot be changed through it.

Next steps​