Installation

Get started with the EmailList API in minutes. Choose your preferred language below.

cURL / HTTP requests

Make requests directly using cURL or any HTTP client:

curl -X GET https://emaillist.dev/api/v1/projects \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

JavaScript/Node.js

Make requests using fetch() or any HTTP client:

const response = await fetch('https://emaillist.dev/api/v1/projects', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Ruby gem

Add the EmailList API gem to your Gemfile:

gem 'email_list_api'

Then install it:

bundle install

Configure the gem globally using an initializer (recommended for Rails apps):

# config/initializers/email_list_api.rb
EmailListApi.configure do |config|
  config.api_key = ENV['EMAILLIST_API_KEY'] || Rails.application.credentials.dig(:emaillist, :api_key)
  # api_version is optional (defaults to latest based on gem version)
  # config.api_version = 1
end

Then initialize the client. The base URL is automatically determined - no need to specify it!

require 'email_list_api'

# If configured globally, you can create a client without specifying the API key
client = EmailListApi::Client.new

# Or explicitly pass the API key (overrides global config)
client = EmailListApi::Client.new(
  api_key: ENV['EMAILLIST_API_KEY']
)

# Optionally specify API version (defaults to latest)
client = EmailListApi::Client.new(
  api_key: ENV['EMAILLIST_API_KEY'],
  api_version: 1
)

The gem automatically uses https://emaillist.dev/api/v1 in production, or http://localhost:3000/api/v1 in development/test environments. The documentation always shows production URLs.

Rails integration

The Ruby gem includes a Rails concern that automatically syncs your models to EmailList contacts. Learn more about the Rails integration → 

class User < ApplicationRecord
  include EmailListApi::SyncsEmailListContact
  
  syncs_email_list_contact project_slug: 'newsletter'
end

Environment variables

For security, always store your API key in environment variables. Never commit API keys to version control. 

# .env file
EMAILLIST_API_KEY=your-api-key-here

Getting your API key

  1. Sign in to your EmailList dashboard
  2. Navigate to Settings → API keys
  3. Click "Create new API key"
  4. Copy the key immediately - it won't be shown again!