DOCSEARCHbyAlgolia
Submit Docs

Mailkick

repository·master·Indexed 21 days ago

https://github.com/ankane/mailkick

A Ruby on Rails gem for managing email subscriptions. Mailkick provides tools for adding one-click unsubscribe links and RFC 8058 headers to emails, and automatically fetches bounces and spam reports from providers including AWS SES, Mailchimp, Mailgun, Mandrill, Postmark, and SendGrid to keep subscriber lists clean.

Tokens
6.6K
Snippets
39
Records
41
Agent score
75%

What's inside mailkick

  3. Upgrade to Mailkick 2.0

    master

    Unsubscribe Link Compatibility

    Unsubscribe links created before version 1.1.1 (January 2023) will not work by default. To restore support, use the rotate method in an initializer with your previous secret token and Marshal serializer:

    Mailkick.message_verifier.rotate(previous_secret_token, serializer: Marshal)

    Postmark Stream Configuration

    In 2.0, Postmark uses the suppressions API and defaults to the broadcast stream. To use the outbound stream instead, configure the service manually:

    Mailkick.services = [
  Mailkick::Service::Postmark.new(api_key: api_key, stream_id: "outbound")
]

  5. Install Mailkick

    master

    Add mailkick to your Gemfile, run the installation generator to create the necessary subscription tables, and migrate your database.

    # Gemfile
gem "mailkick"
    bundle install
rails generate mailkick:install
rails db:migrate

  6. Fetch bounces and spam reports from email services

    master

    Mailkick can synchronize opt-outs (bounces, spam reports, unsubscribes) from your email provider.

    1. Define a processing logic using Mailkick.process_opt_outs_method. This lambda receives an array of opt_outs (each containing :email and :time).
    2. Run Mailkick.fetch_opt_outs to trigger the fetch process.

    Supported services require specific gems and environment variables (see service-specific records).

    # config/initializers/mailkick.rb
Mailkick.process_opt_outs_method = lambda do |opt_outs|
  emails = opt_outs.map { |v| v[:email] }
  subscribers = User.includes(:mailkick_subscriptions).where(email: emails).index_by(&:email)

  opt_outs.each do |opt_out|
    subscriber = subscribers[opt_out[:email]]
    next unless subscriber

    subscriber.mailkick_subscriptions.each do |subscription|
      # Destroy subscriptions created before the opt-out event time
      subscription.destroy if subscription.created_at < opt_out[:time]
    end
  end
end

# To execute the fetch:
Mailkick.fetch_opt_outs

  7. Configure AWS SES for opt-out fetching

    master

    To use AWS SES, add the aws-sdk-sesv2 gem and ensure your AWS credentials are configured. The IAM user/role requires the ses:ListSuppressedDestinations permission.

    Note: If using SES before November 25, 2019, you may need to manually enable the account-level suppression list feature.

    gem "aws-sdk-sesv2"

  10. Add unsubscribe links to emails

    master

    Use the mailkick_unsubscribe_url helper to generate links for your emails. This works for both HTML and text formats. When clicked, users are directed to a mobile-friendly page where they can confirm unsubscription or resubscribe. You can customize the unsubscription view by running the mailkick:views generator.

    # HTML emails
<%= link_to "Unsubscribe", mailkick_unsubscribe_url(@user, "sales") %>

# Text emails
Unsubscribe: <%= mailkick_unsubscribe_url(@user, "sales") %>
    # To customize the unsubscription view:
rails generate mailkick:views

  11. Enable one-click unsubscribe headers (RFC 8058)

    master

    To support one-click unsubscribe headers, enable them in a Mailkick initializer. These headers will be automatically added to any email that utilizes the mailkick_unsubscribe_url helper.

    # config/initializers/mailkick.rb
Mailkick.headers = true

  12. Install Mailkick using the Rails generator

    master

    Mailkick provides a Rails generator to automate the installation process, including the creation of the necessary migration file for tracking subscriptions. Running the generator will create a migration file named db/migrate/create_mailkick_subscriptions.rb which sets up the required database schema for Mailkick to function.

    rails generate mailkick:install