Subscribe API

Use the Subscribe API to add subscribers from custom forms, CRM integrations, landing page builders, or any application. No authentication token is required — the endpoint is designed to be called from client-side code.

Endpoint

POST https://distill.ink/api/subscribe

Content-Type: application/json

Request body

Authentication

Examples

cURL

curl -X POST https://distill.ink/api/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "YOUR_LIST_ID",
    "email": "subscriber@example.com",
    "first_name": "Jane",
    "source": "api"
  }'

JavaScript

const response = await fetch("https://distill.ink/api/subscribe", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    list_id: "YOUR_LIST_ID",
    email: "subscriber@example.com",
    first_name: "Jane",
    source: "api",
  }),
});
 
const data = await response.json();
console.log(data);

Responses

Success — pending confirmation (200)

The subscriber was created. A confirmation email has been sent to the address.

{ "success": true, "status": "pending_confirmation", "message": "Confirmation email sent. Please check your inbox." }

Already subscribed (200)

The email address is already on the list. No duplicate is created.

{ "success": true, "status": "already_subscribed", "message": "You're already subscribed!" }

Validation error (400)

The request body failed validation. Check the error message for details.

{ "error": "Invalid email format" }

Rate limited (429)

The rate limit was exceeded. Wait for the reset window before retrying.

{ "error": "Too many requests. Please try again later." }

Rate limits

Error codes

Finding your list ID

Your list ID is a UUID assigned when the subscriber list is created. To find it:

1. Click the Users icon (Subscribers) in the sidebar.
2. Select the subscriber list you want to use.
3. The list ID appears in the list settings panel.

You can also copy it directly from the embed code in the Form Builder — it is the value in the list_id or data-list-id field.

Troubleshooting

Getting 400 errors? Verify that the email field is a properly formatted email address and that list_id is a valid UUID. If you copied the list ID from the dashboard, make sure no extra spaces or characters were included.

Subscriber not appearing in the dashboard? New subscribers start with Pending status. They must click the confirmation email to become Confirmed and appear in your active subscriber count. Filter by Pending in the Subscribers list to see them.

Getting 429 responses? You have exceeded the rate limit of 10 requests per hour per IP. Read the X-RateLimit-Reset header value (a Unix timestamp) to determine when the window resets. If your integration sends many signups in short bursts, consider batching requests or adding a queue.

Next steps

• Form Builder & Hosted Pages
• Adding Subscribers