Using unsubscribe URLs in emails

When sending emails to your contacts, you need to include unsubscribe links to comply with email regulations and best practices. EmailList provides unsubscribe URLs that you can include in your email templates.

Getting unsubscribe URLs

Unsubscribe URLs are automatically included in API responses when you fetch contacts. There are two ways to get them:

For a specific list

When fetching contacts from a specific list, each contact includes a single unsubscribe_url for that list. This is the most common use case when sending emails to a specific list.

GET /api/v1/projects/:project_id/lists/:list_id/contacts

Fetch contacts from a specific list. Each contact includes an unsubscribe_url for that list.

Parameters

Name Type Required Description
project_id integer Yes The project ID
list_id integer Yes The list ID

Success response (200) 

response = client.list_contacts(project: 'my-project', list_id: 1)

response[:data].each do |contact|
  email = contact[:email]
  unsubscribe_url = contact[:unsubscribe_url]
  # => "https://emaillist.dev/unsubscribe/abc123token..."
  
  # Send email with unsubscribe link
  send_email(email, unsubscribe_url)
end

For all lists a contact belongs to

When fetching a contact directly, you get an unsubscribe_urls hash mapping list IDs to unsubscribe URLs. Use this when you need unsubscribe URLs for multiple lists.

GET /api/v1/projects/:project_id/contacts/:id

Fetch a specific contact. The response includes unsubscribe_urls hash with URLs for all lists the contact belongs to.

Parameters

Name Type Required Description
project_id integer Yes The project ID
id integer Yes The contact ID

Success response (200) 

contact = client.contact(project: 'my-project', id: 1)

# Get unsubscribe URLs for all lists
unsubscribe_urls = contact[:data][:unsubscribe_urls]
# => {
#   1 => "https://emaillist.dev/unsubscribe/abc123token...",
#   2 => "https://emaillist.dev/unsubscribe/def456token..."
# }

# Use the URL for the specific list you're emailing about
list_id = 1
unsubscribe_url = unsubscribe_urls[list_id]

Adding unsubscribe links to email templates

Once you have the unsubscribe URL from the API response, include it in your email templates. Here are examples for common email systems:

General email template example

Include the unsubscribe URL in the footer of your emails: 

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
</head>
<body>
  <h1>Welcome to our newsletter!</h1>
  <p>Here's your weekly update...</p>
  
  <hr>
  <p style="font-size: 12px; color: #666;">
    Don't want to receive these emails anymore?
    <a href="UNSUBSCRIBE_URL">Unsubscribe here</a>.
  </p>
</body>
</html>

Replace UNSUBSCRIBE_URL with the actual unsubscribe URL from the API response.

Complete workflow example

Here's a complete example showing how to send emails to all contacts in a list: 

# Fetch all contacts in a list (with unsubscribe URLs)
page = 1
loop do
  response = client.list_contacts(project: 'my-project', list_id: 1, page: page)
  contacts = response[:data]
  
  break if contacts.empty?
  
  contacts.each do |contact|
    # Each contact has an unsubscribe_url for this specific list
    send_email(
      to: contact[:email],
      unsubscribe_url: contact[:unsubscribe_url]
    )
  end
  
  # Check if there are more pages
  meta = response[:meta]
  break if page >= meta[:total_pages]
  
  page += 1
end

Best practices

  • Always include unsubscribe links: Include an unsubscribe link in every marketing email you send to comply with email regulations (CAN-SPAM, GDPR, etc.)
  • Use list-specific URLs: When sending emails about a specific list, use the unsubscribe_url from the list contacts endpoint
  • Make it visible: Place the unsubscribe link in the footer of your emails where recipients can easily find it
  • Use clear text: Use clear, user-friendly text like "Unsubscribe" or "Manage preferences" rather than hiding the link
  • Fetch URLs when sending: Always fetch the unsubscribe URL right before sending the email to ensure it's current and valid
  • One URL per list: Each unsubscribe URL is specific to a contact-list combination. If a contact is in multiple lists, use the appropriate URL for each list

Note: Unsubscribe URLs are unique to each contact-list combination and are automatically generated when a contact is added to a list. The URLs are secure tokens that allow recipients to unsubscribe without requiring authentication. When a recipient clicks the unsubscribe link, they'll see a page where they can choose to unsubscribe from specific lists or all lists in the project.

Related documentation

  • List contacts API - Learn more about fetching contacts from lists
  • Contacts API - Learn more about fetching individual contacts
  • Ruby SDK - Rails integration and automatic contact syncing