DOCSEARCHbyAlgolia
Submit Docs

postmark-rails Documentation

repository·main·Indexed 18 days ago

https://github.com/activecampaign/postmark-rails

A drop-in plugin for ActionMailer that enables Rails applications to send emails via the Postmark service. Built on top of the postmark gem, it supports all Postmark features, including metadata attachment via ActionMailerExtensions and the use of Postmark templates through the TemplatedMailerMixin.

Tokens
1.3K
Snippets
6
Records
8
Agent score
63%

What's inside postmark-rails

  1. Customize postmark_settings

    main
    The config.action_mailer.postmark_settings hash in your Rails configuration can contain any options supported by the Postmark::ApiClient. This allows you to pass advanced configuration directly through ActionMailer to the underlying Postmark API client.

  2. Configure Postmark for Rails 3, 4, and 5

    main

    For older Rails versions, use config/secrets.yml to store your Postmark Server API Token.

    1. Add the token to config/secrets.yml:
      postmark_api_token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    2. Set the delivery method and settings in config/application.rb:
      config.action_mailer.delivery_method = :postmark
config.action_mailer.postmark_settings = { :api_token => Rails.application.secrets.postmark_api_token }
    config.action_mailer.delivery_method = :postmark
config.action_mailer.postmark_settings = { :api_token => Rails.application.secrets.postmark_api_token }

  3. Configure Postmark for Rails 6 and 7

    main

    For Rails 6 and 7, use Rails credentials to store your Postmark Server API Token.

    1. Add the token to config/credentials.yml.enc:
      postmark_api_token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    2. Set the delivery method and settings in config/application.rb:
      config.action_mailer.delivery_method = :postmark
config.action_mailer.postmark_settings = { api_token: Rails.application.credentials.postmark_api_token }
    config.action_mailer.delivery_method = :postmark
config.action_mailer.postmark_settings = { api_token: Rails.application.credentials.postmark_api_token }

  5. Use TemplatedMailer to send Postmark templates via ActionMailer

    main

    The PostmarkRails::TemplatedMailerMixin allows you to use Postmark templates within your Rails mailers. When included in a mailer, it automatically manages the message body and subject to reflect the template being used.

    To use it, include the mixin in your mailer class. You can then set the template_model (the data passed to the template) directly on the mailer instance.

    Important Constraints:

    • You cannot manually override the body, content_type, or subject headers in a templated mailer. Attempting to do so will raise an ArgumentError.
    • The mailer uses a postmark_template_alias to identify which Postmark template to use.
    class MyMailer < ActionMailer::Base
  include PostmarkRails::TemplatedMailerMixin

  def welcome_email(user)
    @user = user
    # Set the data to be passed to the Postmark template
    template_model = { name: user.name, email: user.email }
    
    # The template_alias is typically derived from the action_name
    mail(template_model: template_model)
  end
end

  7. Access and set message metadata via ActionMailerExtensions

    main

    The PostmarkRails::ActionMailerExtensions module is included in ActionMailer::Base to allow attaching metadata to outgoing emails. This is useful for passing custom information to Postmark. You can use the metadata getter and setter on your mailer instances or within your mail methods.

    # Example of setting metadata in a mailer method
class UserMailer < ActionMailer::Base
  def welcome_email(user)
    @user = user
    mail(to: @user.email, subject: 'Welcome!') do |format|
      metadata(custom_id: '123', category: 'onboarding')
    end
  end
end

  8. Manage template data with template_model

    main

    In a mailer using PostmarkRails::TemplatedMailerMixin, you can manage the data passed to your Postmark template using the template_model method. This method acts as a getter and setter for the template's data payload.

    • template_model: Returns the current model/data hash.
    • template_model=(model): Sets the data hash to be used when the template is rendered.
    class UserMailer < ActionMailer::Base
  include PostmarkRails::TemplatedMailerMixin

  def signup_notification(user)
    # Setting the template model
    self.template_model = { user_id: user.id, name: user.name }
    mail
  end
end