DOCSEARCHbyAlgolia
Submit Docs

Postmark Ruby Gem

repository·main·Indexed 42 days ago

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

The official Ruby wrapper for the Postmark HTTP API. It allows developers to send single or batch emails, manage templates, handle bounces, and retrieve delivery statistics. The gem includes an ApiClient for general API interactions and an AccountApiClient for managing senders, domains, and servers. It also provides integration options for Rails via the postmark-rails gem.

Tokens
6.1K
Snippets
24
Records
31
Agent score
53%

What's inside Postmark

  1. Integrate Postmark with Rails ActionMailer

    main
    If you are working within a Rails project and want to use Postmark with ActionMailer, use the postmark-rails gem instead of the base gem. The postmark-rails plugin automatically attempts to use ActiveSupport JSON if available, otherwise it falls back to the built-in Ruby JSON library.

  2. Install the Postmark Ruby Gem

    main

    You can install the Postmark gem using Bundler or by installing it directly via the command line.

    Using Bundler: Add the following to your Gemfile:

    gem 'postmark'

    Without Bundler: Run the following command in your terminal:

    gem install postmark
    gem 'postmark'

  3. Configure the JSON response parser

    main

    When using the gem (especially in Rails projects), you can explicitly specify which class should be used to parse JSON responses. Supported options are :Json, :ActiveSupport, and :Yajl.

    Postmark.response_parser_class = :Json # :ActiveSupport or :Yajl are also supported.

  4. Configure deprecation behavior

    main

    You can control how the gem handles deprecation warnings by setting the Postmark::Deprecations.behavior. You can either silence the warnings or force them to raise an error.

    Postmark::Deprecations.behavior = :silence
Postmark::Deprecations.behavior = :raise

  5. Configure the Postmark gem

    main

    Use the Postmark.configure block to set up your API credentials and connection settings. This configuration is applied globally to the Postmark.api_client used for all requests.

    Available configuration attributes include:

    • api_token (or api_key): Your Postmark API token.
    • secure: Boolean indicating if SSL/TLS should be used.
    • host: The API host.
    • port: The API port.
    • path_prefix: A prefix for all API paths.
    • http_open_timeout: Timeout for opening the HTTP connection.
    • http_read_timeout: Timeout for reading from the HTTP connection.
    • max_retries: Number of times to retry failed requests.
    • proxy_host, proxy_port, proxy_user, proxy_pass: Proxy server settings.
    Postmark.configure do |config|
  config.api_token = 'your-api-token'
  config.secure = true
  config.max_retries = 3
end

  6. Initialize the Postmark ApiClient

    main

    To interact with the Postmark API, instantiate Postmark::ApiClient with your API token. You can optionally provide a :max_batch_size option to control how many messages are sent in a single batch request. The default batch size is 500.

    client = Postmark::ApiClient.new('your-api-token', max_batch_size: 100)

  7. Configure the API client and response parser

    main

    You can override the default global API client or change how JSON responses are parsed.

    • Postmark.api_client = custom_client: Assigns a custom instance of Postmark::ApiClient.
    • Postmark.response_parser_class = parser_symbol: Sets the parser to use. Supported symbols include :Json, :ActiveSupport, and :Yajl. By default, it uses :ActiveSupport if defined, otherwise :Json.

  8. Deprecated: Use native Mail attachments instead of postmark_attachments

    main

    The postmark_attachments= and postmark_attachments methods on Mail::Message are deprecated and will be removed in the future.

    Instead of using these Postmark-specific methods, you should use the native attachments API provided by the Mail library. The export_attachments method will automatically combine both native attachments and any legacy postmark_attachments to ensure compatibility during transition.

  9. Manage Servers via AccountApiClient

    main

    Use the AccountApiClient to manage Postmark servers.

    Available Methods:

    • servers(options = {}): List servers.
    • get_servers(options = {}): Retrieve a batch of servers.
    • get_servers_count(options = {}): Get the total count of servers.
    • get_server(id): Retrieve a specific server by ID.
    • create_server(attributes = {}): Create a new server.
    • update_server(id, attributes = {}): Update an existing server.
    • delete_server(id): Delete a server.
    client = Postmark::AccountApiClient.new('YOUR_API_TOKEN')
servers = client.servers

  10. Deliver single or multiple messages

    main

    The ApiClient provides several methods for sending emails depending on whether you are using templates or raw message hashes.

    Sending single messages

    • deliver(message_hash): Sends a single message using a hash of attributes.
    • deliver_message(message): Sends a message object. Note: This method will raise an ArgumentError if the message is templated. Use deliver_message_with_template instead.
    • deliver_message_with_template(message): Sends a message object that uses a Postmark template.
    • deliver_with_template(attributes): Sends a single message using a hash of attributes including template information.

    Sending multiple messages (Batching)

    Batching is handled automatically by the client using the configured max_batch_size.

    • deliver_in_batches(message_hashes): Sends an array of message hashes in batches using the /email/batch endpoint.
    • deliver_messages(messages): Sends an array of message objects. Raises ArgumentError if any message is templated.
    • deliver_messages_with_templates(messages): Sends an array of message objects where all messages must be templated, using the /email/batchWithTemplates endpoint.
    • deliver_in_batches_with_templates(message_hashes): Sends an array of message hashes in batches using the /email/batchWithTemplates endpoint.
    # Single message via hash
client.deliver({ from: 'sender@example.com', to: 'rcpt@example.com', subject: 'Hello', text_body: 'World' })

# Single message via object (non-templated)
client.deliver_message(my_message_object)

# Batch of hashes
client.deliver_in_batches([{ from: '...', to: '...', ... }, { from: '...', to: '...', ... }])

  11. Push Templates and Manage Data Removals

    main

    The AccountApiClient provides methods for bulk template management and data privacy requests.

    Push Templates:

    • push_templates(attributes = {}): Pushes a batch of templates to Postmark. Returns the batch of templates processed.

    Data Removals:

    • request_data_removal(attributes = {}): Requests the removal of specific data from Postmark.
    • get_data_removal_status(id): Retrieves the status of a previously requested data removal.
    client = Postmark::AccountApiClient.new('YOUR_API_TOKEN')

# Push templates
client.push_templates(templates: [{ name: 'Welcome Email', html_body: '...' }])

# Request data removal
removal = client.request_data_removal(email: 'user@example.com')
status = client.get_data_removal_status(removal['Id'])