Unsubscribes

Manage recipient unsubscribe preferences and view unsubscribe records. FormaMail provides granular unsubscribe management through email categories, allowing recipients to opt out of specific types of emails while continuing to receive others.

Overview

When recipients click the unsubscribe link in your emails, they can choose to:

• Unsubscribe from a category: Stop receiving specific types of emails
• Unsubscribe from all: Stop receiving all marketing emails

Unsubscribe records are stored and automatically honored for future sends.

Accessing Unsubscribes

Navigate to Settings → Unsubscribes in the sidebar, or go directly to /settings/unsubscribes.

Unsubscribe Records

Viewing Unsubscribes

The Unsubscribes page displays all unsubscribe records with:

Search and Filter

Use the search and filter options:

• Search: Find specific email addresses
• Filter by Category: View unsubscribes for a specific category
• Filter by Date: View unsubscribes within a date range

How Unsubscribe Works

The Unsubscribe Flow

1. Email Sent: An email is sent using a template with assigned categories
2. Link Clicked: Recipient clicks the unsubscribe link in the email footer
3. Options Shown: Unsubscribe page displays category options based on the template
4. Choice Made: Recipient selects categories to unsubscribe from (or all)
5. Record Created: Unsubscribe record is stored in the database
6. Future Sends Blocked: Emails to this recipient using templates with unsubscribed categories are automatically blocked

Unsubscribe Page

The unsubscribe page shows:

• Categories assigned to the email’s template
• Option to unsubscribe from individual categories
• Option to unsubscribe from all emails
• Confirmation message after unsubscribing

Automatic Blocking

When sending emails, FormaMail automatically checks:

1. Is the recipient on the suppression list?
2. Has the recipient unsubscribed from any categories assigned to this template?

If either condition is true, the email is blocked and logged as “Suppressed” or “Unsubscribed”.

Category-Based Unsubscribes

Single Category Unsubscribe

Recipients can unsubscribe from individual categories:

Example: A recipient unsubscribes from “Marketing” category

• They will stop receiving emails from templates assigned to “Marketing”
• They will continue receiving emails from templates assigned to other categories
• They will receive emails from templates with no category assigned

Multiple Category Unsubscribe

Recipients can unsubscribe from multiple categories at once by checking multiple options on the unsubscribe page.

Complete Unsubscribe

If a recipient chooses “Unsubscribe from all”:

• Records are created for all categories assigned to the template
• A global unsubscribe record is also created
• All future marketing emails are blocked

Managing Unsubscribes

Resubscribing a Recipient

If a recipient requests to be resubscribed:

1. Find the email in the Unsubscribes list
2. Click the “Remove” button
3. Confirm the removal

Important: Only remove unsubscribes if you have explicit consent from the recipient.

Bulk Management

Select multiple unsubscribe records to:

• Remove selected (resubscribe)
• Export to CSV

Adding Manual Unsubscribes

You can manually add unsubscribe records:

1. Click “Add Unsubscribe”
2. Enter the email address
3. Select the category (or “All Categories”)
4. Click “Add”

Use this when:

• Processing unsubscribe requests received via other channels (phone, email)
• Pre-loading unsubscribes from another email system

Statistics

The Unsubscribes page displays key metrics:

Unsubscribe Links

Automatic Link Insertion

FormaMail automatically adds an unsubscribe link to the footer of all emails. This link:

• Is unique per recipient and email
• Contains tracking information
• Directs to a hosted unsubscribe page

List-Unsubscribe Header

FormaMail also adds a List-Unsubscribe header to emails, enabling one-click unsubscribe in supported email clients (Gmail, Yahoo, etc.).

Custom Unsubscribe Links

You can include custom unsubscribe links in your template using:

{{unsubscribeUrl}}

This variable is automatically replaced with the unique unsubscribe URL for each recipient.

API Integration

Manage unsubscribes programmatically:

// List unsubscribes
const unsubscribes = await api.get('/unsubscribes', {
  params: {
    categoryId: 'optional-category-id',
    page: 1,
    limit: 50
  }
});
 
// Check if email is unsubscribed
const check = await api.get('/unsubscribes/check', {
  params: {
    email: 'user@example.com',
    categoryId: 'optional-category-id'
  }
});
 
// Add unsubscribe
await api.post('/unsubscribes', {
  email: 'user@example.com',
  categoryId: 'category-id' // optional, null for global unsubscribe
});
 
// Remove unsubscribe (resubscribe)
await api.delete('/unsubscribes/record-id');
 
// Bulk add unsubscribes
await api.post('/unsubscribes/bulk', {
  emails: ['user1@example.com', 'user2@example.com'],
  categoryId: 'category-id'
});

See the API Reference for complete endpoint documentation.

Best Practices

Honor Unsubscribes Immediately

• Process unsubscribes in real-time
• Don’t queue emails to unsubscribed addresses
• FormaMail handles this automatically

Provide Category Options

• Assign categories to all templates
• Let recipients choose granular preferences
• Reduce complete unsubscribes

Regular Review

• Monitor unsubscribe rates
• Investigate spikes in unsubscribes
• Adjust content strategy if needed

Compliance

• Keep unsubscribe records for compliance
• Process unsubscribes within 10 days (CAN-SPAM)
• Immediately for GDPR

Troubleshooting

Recipient Says They Unsubscribed But Still Receiving Emails

Check these possibilities:

1. Wrong Template: The email may use a template without the unsubscribed category
2. No Category on Template: Template may not have any categories assigned
3. Timing: Email may have been queued before unsubscribe was processed
4. Different Email: Check if unsubscribe was for a different email address

Unsubscribe Link Not Working

1. Check if the link is complete (not truncated)
2. Verify the link hasn’t expired
3. Check if the email was sent through FormaMail

High Unsubscribe Rates

If you’re seeing high unsubscribe rates:

1. Review email frequency - are you sending too often?
2. Check content relevance - is content targeted?
3. Review segmentation - are the right people receiving?
4. Check subject lines - are they misleading?

Unsubscribes vs. Suppression List

Use Suppression List for: Hard bounces, complaints, known bad addresses

Use Unsubscribes for: Recipient opt-out preferences

Related Features

• Email Categories - Create categories for unsubscribe options
• Templates - Assign categories to templates
• Suppression List - Block addresses from receiving emails
• Email Logs - View suppressed/unsubscribed delivery status

Related: Email Categories | Suppression List | Settings