### Install Goodmail Gem

Source: https://github.com/rameerez/goodmail/blob/main/README.md

Add the Goodmail gem to your application's Gemfile to include its functionality. After adding the gem, run `bundle install` to install it and its dependencies.

```ruby
gem "goodmail"
```

--------------------------------

### Create Call-to-Action Buttons with VML Fallback

Source: https://context7.com/rameerez/goodmail/llms.txt

Explains the `button` DSL method for generating styled call-to-action buttons. It includes VML fallbacks for Outlook compatibility and automatically applies the configured brand color. The example shows its usage within an email composition, along with adding vertical spacing using the `space` method.

```ruby
Goodmail.compose(
  to: "user@example.com",
  from: "notifications@myapp.com",
  subject: "Confirm Your Email"
) do
  h2 "Email Confirmation Required"
  text "Please confirm your email address to activate your account."
  button "Confirm Email", "https://myapp.com/confirm?token=abc123"
  space 32  # Add vertical spacing
  text "This link expires in 24 hours."
end
```

--------------------------------

### Configure Goodmail Initialization

Source: https://github.com/rameerez/goodmail/blob/main/README.md

Configure Goodmail by creating an initializer file (`config/initializers/goodmail.rb`). This involves setting essential branding information like `company_name` and optional details such as `brand_color`, `logo_url`, and footer content. The application will error on startup if required configuration is missing.

```ruby
# config/initializers/goodmail.rb

Goodmail.configure do |config|
  # --- Basic Branding (Required) ---

  # The company name displayed in the email footer and used by `sign` helper.
  # NOT OPTIONAL - MUST BE SET
  config.company_name = "MyApp Inc."

  # --- Optional Branding ---

  # The main accent color used for buttons and links in the email body.
  config.brand_color = "#E62F17"

  # Optional: URL to your company logo. If set, it will appear in the header.
  # Default: nil
  config.logo_url = "https://cdn.myapp.com/images/email_logo.png"

  # Optional: URL the header logo links to (e.g., your homepage).
  # Ignored if logo_url is not set. Must be a valid URL (no spaces etc.).
  # Default: nil
  config.company_url = "https://myapp.com"

  # --- Optional Email Content Defaults ---

  # Optional: Default preheader text (appears after subject in inbox preview).
  # Can be overridden per email via headers[:preheader]. If unset, subject is used.
  # Default: nil
  config.default_preheader = "Your account update from MyApp."

  # Optional: Global default URL for unsubscribe links.
  # Goodmail *does not* handle the unsubscribe logic; you must provide a valid URL.
  # Can be overridden per email via headers[:unsubscribe_url].
  # Default: nil
  config.unsubscribe_url = "https://myapp.com/emails/unsubscribe"

  # --- Optional Footer Customization ---

  # Optional: Custom text displayed in the footer below the copyright.
  # Use this to explain why the user received the email.
  # Default: nil
  config.footer_text = "You are receiving this email because you signed up for an account at MyApp."

  # Optional: Whether to show a visible unsubscribe link in the footer.
  # Requires an unsubscribe URL to be set (globally or per-email).
  # Default: false
  config.show_footer_unsubscribe_link = true

  # Optional: The text for the visible footer unsubscribe link.
  # Default: "Unsubscribe"
  config.footer_unsubscribe_link_text = "Click here to unsubscribe"
end
```

--------------------------------

### Compose and Deliver Email Immediately (Deliver Now)

Source: https://github.com/rameerez/goodmail/blob/main/README.md

Use the `Goodmail.compose` method with the provided DSL to construct transactional emails. After composing, call `.deliver_now` to send the email immediately. Ensure configuration is set up and provide recipient details, sender address, subject, and email body content.

```ruby
# Assumes config/initializers/goodmail.rb is configured!
recipient = User.find(params[:user_id])

mail = Goodmail.compose(
  to: recipient.email,
  from: "'#{Goodmail.config.company_name} Support' <support@myapp.com>",
  subject: "Welcome to MyApp!",
  preheader: "Your adventure begins now!" # Optional override
) do
  h1 "Welcome aboard, #{recipient.name}!"
  text "We're thrilled to have you join the MyApp community."
  text "Here are a few things: Check the <a href=\"/help\">Help Center</a>."
  button "Go to Dashboard", user_dashboard_url(recipient)
  sign
end

mail.deliver_now
```

--------------------------------

### Configure Goodmail Global Settings

Source: https://context7.com/rameerez/goodmail/llms.txt

Illustrates setting up global configurations for Goodmail, including company branding, colors, and default email parameters. This configuration should be placed in a Rails initializer file (`config/initializers/goodmail.rb`) and requires `company_name` to be set.

```ruby
# config/initializers/goodmail.rb
Goodmail.configure do |config|
  # Required: Company name for footer and signatures
  config.company_name = "MyApp Inc."

  # Optional: Branding
  config.brand_color = "#E62F17"
  config.logo_url = "https://cdn.myapp.com/images/email_logo.png"
  config.company_url = "https://myapp.com"

  # Optional: Email defaults
  config.default_preheader = "Your account update from MyApp."
  config.unsubscribe_url = "https://myapp.com/emails/unsubscribe"

  # Optional: Footer customization
  config.footer_text = "You received this because you signed up at MyApp."
  config.show_footer_unsubscribe_link = true
  config.footer_unsubscribe_link_text = "Click here to unsubscribe"
end

# Raises Goodmail::Error if company_name is missing
```

--------------------------------

### Structure Content with Headings, Lines, and Spacing - Ruby

Source: https://context7.com/rameerez/goodmail/llms.txt

Provides methods for creating headings (h1, h2, h3), horizontal lines, vertical spacing, and centering content. These are used to structure the email's layout and readability.

```ruby
Goodmail.compose(
  to: "user@example.com",
  from: "team@myapp.com",
  subject: "Weekly Summary"
) do
  h1 "Weekly Activity Report"
  text "Here's what happened this week in your account."

  line  # Horizontal divider

  h2 "New Features"
  text "We've launched 3 new features based on your feedback."

  h3 "Performance Improvements"
  text "Your dashboard now loads 50% faster."

  space 32  # 32 pixels of vertical space

  center do
    image "https://cdn.myapp.com/charts/activity.png", "Activity Chart"
    text "View detailed analytics"
  end

  button "View Full Report", "https://myapp.com/reports/weekly"
  sign "The MyApp Team"
end
```

--------------------------------

### Compose and Deliver Mail Object with Action Mailer Headers

Source: https://github.com/rameerez/goodmail/blob/main/README.md

This snippet demonstrates how to create a mail object using Action Mailer headers and then deliver it. It highlights the use of `mail` with headers and rendering different formats (HTML and text). The `final_mail_object` can be delivered immediately or later.

```ruby
final_mail_object = mail(action_mailer_headers) do |format|
  format.html { render html: parts.html.html_safe }
  format.text { render plain: parts.text }
end

# The `final_mail_object` returned by ActionMailer can then be delivered:
# final_mail_object.deliver_now or final_mail_object.deliver_later
```

--------------------------------

### Display Codes and Tokens in Styled Box - Ruby

Source: https://context7.com/rameerez/goodmail/llms.txt

Displays text within a styled box with a gray background, ideal for verification codes or tokens. This method takes a single string argument representing the code to be displayed.

```ruby
Goodmail.compose(
  to: "user@example.com",
  from: "security@myapp.com",
  subject: "Two-Factor Authentication Code"
) do
  h2 "Your Verification Code"
  text "Use this code to complete your login:"
  code_box "847593"
  text "This code expires in 10 minutes."
  space 16
  text "If you didn't request this code, please ignore this email."
end
```

--------------------------------

### Configure Unsubscribe Management - Ruby

Source: https://context7.com/rameerez/goodmail/llms.txt

Handles List-Unsubscribe headers and optional visible footer links for email preferences. Configuration can be set globally or overridden per email, including dynamic unsubscribe URLs.

```ruby
# Global configuration in initializer
Goodmail.configure do |config|
  config.company_name = "MyApp Inc."
  config.unsubscribe_url = "https://myapp.com/preferences"
  config.show_footer_unsubscribe_link = true
  config.footer_unsubscribe_link_text = "Manage email preferences"
end

# Per-email override with dynamic URL
user = User.find(params[:id])
mail = Goodmail.compose(
  to: user.email,
  from: "marketing@myapp.com",
  subject: "Product Updates",
  unsubscribe_url: manage_subscription_url(user, token: user.unsubscribe_token)
) do
  h1 "What's New at MyApp"
  text "Check out our latest features and improvements."
  button "See What's New", "https://myapp.com/updates"
end

mail.deliver_now
# Automatically includes List-Unsubscribe header
# Shows footer link if show_footer_unsubscribe_link is enabled
```

--------------------------------

### Configure Goodmail Gem for Unsubscribe Features

Source: https://github.com/rameerez/goodmail/blob/main/README.md

This Ruby code snippet shows how to configure the Goodmail gem globally using an initializer file. It demonstrates setting the `unsubscribe_url`, enabling the display of a footer unsubscribe link, and customizing the link's text. These settings affect how unsubscribe functionality is handled for emails composed with the gem.

```ruby
# config/initializers/goodmail.rb
Goodmail.configure do |config|
  config.unsubscribe_url = "https://myapp.com/preferences"
  config.show_footer_unsubscribe_link = true
  config.footer_unsubscribe_link_text = "Manage email preferences"
  # ...
end
```

--------------------------------

### Compose and Send Emails with Goodmail

Source: https://context7.com/rameerez/goodmail/llms.txt

Demonstrates how to compose a Mail::Message object using the Goodmail DSL for immediate or background delivery. It utilizes the `compose` method with recipient details, subject, preheader, and custom content elements. Requires a Rails application context.

```ruby
recipient = User.find(params[:user_id])

mail = Goodmail.compose(
  to: recipient.email,
  from: "'MyApp Support' <support@myapp.com>",
  subject: "Welcome to MyApp!",
  preheader: "Your adventure begins now!"
) do
  h1 "Welcome aboard, #{recipient.name}!"
  text "We're thrilled to have you join the MyApp community."
  text "Here are a few things: Check the <a href=\"#">Help Center</a>."
  button "Go to Dashboard", "https://myapp.com/dashboard"
  sign
end

mail.deliver_now
# => Sends email immediately

# Background job delivery
mail.deliver_later
# => Queues email for background processing with Active Job
```

--------------------------------

### Add Receipt Line Items with Borders - Ruby

Source: https://context7.com/rameerez/goodmail/llms.txt

Adds styled price rows with borders, suitable for receipts and invoices. Each row requires a description and a price, and multiple rows can be chained together.

```ruby
Goodmail.compose(
  to: "customer@example.com",
  from: "billing@myapp.com",
  subject: "Payment Receipt"
) do
  h1 "Payment Received"
  text "Thank you for your payment!"
  space 24
  price_row "Pro Plan Subscription", "$29.00"
  price_row "Additional Storage (50GB)", "$5.00"
  price_row "Tax", "$2.72"
  price_row "Total", "$36.72"
  space 24
  button "View Invoice", "https://myapp.com/invoices/inv-2024-001"
end
```

--------------------------------

### Render Email Parts for Custom Mailers

Source: https://context7.com/rameerez/goodmail/llms.txt

Shows how to render HTML and plain text email parts using `Goodmail.render` without creating a full `Mail::Message` object. This is useful for integrating with existing mailers like Devise. The output can be directly used within Action Mailer views.

```ruby
# Generate email parts for custom mailer integration
mail_headers = {
  to: user.email,
  from: "notifications@myapp.com",
  subject: "Password Reset Instructions",
  unsubscribe_url: custom_unsubscribe_url_for_user(user),
  preheader: "Reset your password now"
}

parts = Goodmail.render(mail_headers) do
  h1 "Password Reset"
  text "Click the button below to reset your password."
  code_box "ABC123XYZ"
  button "Reset Password", "https://myapp.com/reset?token=#{user.reset_token}"
  sign "The MyApp Team"
end

# parts.html contains CSS-inlined HTML
# parts.text contains cleaned plain text version

# Use in Action Mailer
mail(mail_headers.slice(:to, :from, :subject)) do |format|
  format.html { render html: parts.html.html_safe }
  format.text { render plain: parts.text }
end
```

--------------------------------

### Compose Email with Goodmail DSL

Source: https://github.com/rameerez/goodmail/blob/main/README.md

Demonstrates using Goodmail's DSL within a `Goodmail.compose` block to define the content and structure of an email. This method is suitable for direct email composition and sending.

```ruby
Goodmail.compose do
  h1 "Welcome!"
  text "Thanks for signing up."
  button "Get Started", "/signup"
end
```

--------------------------------

### Render Email Parts with Goodmail.render (Ruby)

Source: https://github.com/rameerez/goodmail/blob/main/README.md

Illustrates using `Goodmail.render` to generate separate HTML and plain text parts of an email. This is useful for integrating with existing mailer systems like Action Mailer, where you need explicit control over email components before sending.

```ruby
# In your custom mailer (e.g., a Devise mailer override)

# Define your headers (to, from, subject, etc.)
# The :subject is crucial for Goodmail.render.
# You can also pass :unsubscribe_url and :preheader to Goodmail.render
# to override global configurations for that specific email.
# Note: these Goodmail-specific keys will be used by Goodmail.render
# and should not be passed directly to ActionMailer's mail() method
# if they are not standard mail headers.
mail_rendering_headers = {
  to: recipient.email,
  from: "notifications@myapp.com",
  subject: "Important Update for #{recipient.name}",
  unsubscribe_url: custom_unsubscribe_url_for_user(recipient), # Optional
  preheader: "A quick update you should see." # Optional
}

# Render the email parts using Goodmail's DSL
# Goodmail.render will use :subject, :unsubscribe_url, :preheader internally.
parts = Goodmail.render(mail_rendering_headers) do
  h1 "Hello, #{recipient.name}!"
  text "This is an important update regarding your account."
  button "View Details", view_details_url(recipient)
  sign "The MyApp Team"
end

# Prepare headers for ActionMailer's mail() method,
# ensuring only standard mail headers are passed.
action_mailer_headers = mail_rendering_headers.slice(:to, :from, :subject, :cc, :bcc, :reply_to)

# Now use these parts in ActionMailer's mail method
mail(action_mailer_headers) do |format|
  format.html { render :text => parts.html }
  format.text { render :text => parts.text }
end
```

--------------------------------

### Compose and Deliver Email Later (Background Job)

Source: https://github.com/rameerez/goodmail/blob/main/README.md

Compose emails using `Goodmail.compose` and the DSL, then use `.deliver_later` to send them asynchronously as background jobs. This requires Active Job to be configured in your Rails application. The method signature and DSL usage are similar to `.deliver_now`.

```ruby
mail = Goodmail.compose(
  to: @user.email,
  from: ..., # etc.
  subject: "Your password has been reset"
) do
  # ... DSL content ...
end

mail.deliver_later
```

--------------------------------

### Embed Centered Images with MSO Fallback - Ruby

Source: https://context7.com/rameerez/goodmail/llms.txt

Embeds centered images with optional dimensions and MSO fallback for Outlook. This method requires a URL for the image and an alt text, with optional width and height parameters.

```ruby
Goodmail.compose(
  to: "customer@example.com",
  from: "store@myapp.com",
  subject: "Order Shipped"
) do
  h1 "Your Order is On Its Way!"
  image "https://cdn.myapp.com/products/item-123.jpg",
        "Product Image",
        width: 400,
        height: 300
  text "Your order #12345 has been shipped and will arrive in 2-3 business days."
  button "Track Shipment", "https://myapp.com/orders/12345/track"
end
```

--------------------------------

### Add Text Paragraphs with Links and Line Breaks

Source: https://context7.com/rameerez/goodmail/llms.txt

Demonstrates the `text` DSL method for adding paragraphs to emails. It supports inline HTML links (sanitized to `<a>` tags only) and interprets newline characters (`\n`) as `<br>` tags for line breaks.

```ruby
Goodmail.compose(
  to: "user@example.com",
  from: "support@myapp.com",
  subject: "Account Update"
) do
  text "Your account has been updated successfully."
  text "Visit your <a href=\"https://myapp.com/profile\">profile page</a> to review changes."
  text "Questions? Contact us.\n\nWe're here to help!"
  # \n creates line breaks with <br> tags
end
```

--------------------------------

### Integrate Custom HTML - Ruby

Source: https://context7.com/rameerez/goodmail/llms.txt

Allows inserting raw HTML for advanced use cases. Content is not sanitized, so use with extreme caution. This method appends raw HTML strings to the email body.

```ruby
Goodmail.compose(
  to: "user@example.com",
  from: "system@myapp.com",
  subject: "System Status Report"
) do
  h1 "System Status Report"
  text "All systems operational."

  # Insert custom HTML table
  html <<~HTML
    <table style="width:100%; border-collapse:collapse;">
      <tr>
        <th style="border:1px solid #ddd; padding:8px;">Service</th>
        <th style="border:1px solid #ddd; padding:8px;">Status</th>
      </tr>
      <tr>
        <td style="border:1px solid #ddd; padding:8px;">API</td>
        <td style="border:1px solid #ddd; padding:8px; color:green;">Online</td>
      </tr>
      <tr>
        <td style="border:1px solid #ddd; padding:8px;">Database</td>
        <td style="border:1px solid #ddd; padding:8px; color:green;">Online</td>
      </tr>
    </table>
  HTML

  space 24
  sign
end
```

--------------------------------

### Compose Mail Message with Unsubscribe URL

Source: https://github.com/rameerez/goodmail/blob/main/README.md

This Ruby code illustrates how to use `Goodmail.compose` to create a `Mail::Message` object, specifically including an `unsubscribe_url`. When an `unsubscribe_url` is provided, the `List-Unsubscribe` header is automatically added to the email.

```ruby
mail = Goodmail.compose(
  to: recipient.email,
  unsubscribe_url: manage_subscription_url(recipient),
  # ... other headers ...
) do # ...
end
```

--------------------------------

### Add Email Signatures - Ruby

Source: https://context7.com/rameerez/goodmail/llms.txt

Appends a closing signature line to the email. It can take a custom name and defaults to the company name if not provided.

```ruby
Goodmail.compose(
  to: "user@example.com",
  from: "ceo@myapp.com",
  subject: "Thank You for Your Support"
) do
  h2 "A Personal Thank You"
  text "I wanted to personally thank you for being an early supporter of MyApp."
  text "Your feedback has been invaluable in shaping our product."
  space 24
  sign "Sarah Chen, CEO"
  # Renders as: – Sarah Chen, CEO
end
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.