Class: PostmarkClient::Email

Inherits:
Object
  • Object
show all
Defined in:
lib/postmark_client/models/email.rb

Overview

Represents an email message for the Postmark API. Provides a clean Ruby interface for building email payloads.

Examples:

Creating a simple email

email = PostmarkClient::Email.new(
  from: "[email protected]",
  to: "[email protected]",
  subject: "Hello!",
  text_body: "Hello, World!"
)

Creating an email with HTML and attachments

email = PostmarkClient::Email.new(
  from: "John Doe <[email protected]>",
  to: ["[email protected]", "[email protected]"],
  cc: "[email protected]",
  subject: "Monthly Report",
  html_body: "<h1>Report</h1><p>See attached.</p>",
  text_body: "Report - See attached.",
  track_opens: true
)
email.add_attachment(name: "report.pdf", content: pdf_data, content_type: "application/pdf")

Using the builder pattern

email = PostmarkClient::Email.new
  .from("[email protected]")
  .to("[email protected]")
  .subject("Hello")
  .text_body("Hello, World!")

Constant Summary collapse 

%w[None HtmlAndText HtmlOnly TextOnly].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(from: nil, to: nil, cc: nil, bcc: nil, subject: nil, html_body: nil, text_body: nil, reply_to: nil, tag: nil, headers: nil, track_opens: nil, track_links: nil, attachments: nil, metadata: nil, message_stream: nil) ⇒ Email

Initialize a new email

Parameters:

  • from (String, nil) (defaults to: nil) —

    sender email address

  • to (String, Array<String>, nil) (defaults to: nil) —

    recipient email address(es)

  • cc (String, Array<String>, nil) (defaults to: nil) —

    CC recipient(s)

  • bcc (String, Array<String>, nil) (defaults to: nil) —

    BCC recipient(s)

  • subject (String, nil) (defaults to: nil) —

    email subject

  • html_body (String, nil) (defaults to: nil) —

    HTML body

  • text_body (String, nil) (defaults to: nil) —

    plain text body

  • reply_to (String, nil) (defaults to: nil) —

    reply-to address

  • tag (String, nil) (defaults to: nil) —

    email tag

  • headers (Array<Hash>, nil) (defaults to: nil) —

    custom headers

  • track_opens (Boolean, nil) (defaults to: nil) —

    track opens

  • track_links (String, nil) (defaults to: nil) —

    link tracking setting

  • attachments (Array<Attachment>, nil) (defaults to: nil) —

    attachments

  • metadata (Hash, nil) (defaults to: nil) —

    custom metadata

  • message_stream (String, nil) (defaults to: nil) —

    message stream



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/postmark_client/models/email.rb', line 99

def initialize(
  from: nil,
  to: nil,
  cc: nil,
  bcc: nil,
  subject: nil,
  html_body: nil,
  text_body: nil,
  reply_to: nil,
  tag: nil,
  headers: nil,
  track_opens: nil,
  track_links: nil,
  attachments: nil,
  metadata: nil,
  message_stream: nil
)
  @from = from
  @to = to
  @cc = cc
  @bcc = bcc
  @subject = subject
  @html_body = html_body
  @text_body = text_body
  @reply_to = reply_to
  @tag = tag
  @headers = headers || []
  @track_opens = track_opens
  @track_links = track_links
  @attachments = attachments || []
  @metadata = metadata || {}
  @message_stream = message_stream || PostmarkClient.configuration.default_message_stream
end

Instance Attribute Details

#attachments ⇒ Array<Attachment>

Returns email attachments.

Returns:



71
72
73
 
# File 'lib/postmark_client/models/email.rb', line 71

def attachments
  @attachments
end

#bcc ⇒ String, ...

Returns BCC recipient email address(es).

Returns:

  • (String, Array<String>, nil) —

    BCC recipient email address(es)



44
45
46
 
# File 'lib/postmark_client/models/email.rb', line 44

def bcc
  @bcc
end

#cc ⇒ String, ...

Returns CC recipient email address(es).

Returns:

  • (String, Array<String>, nil) —

    CC recipient email address(es)



41
42
43
 
# File 'lib/postmark_client/models/email.rb', line 41

def cc
  @cc
end

#from ⇒ String

Returns sender email address.

Returns:

  • (String) —

    sender email address



35
36
37
 
# File 'lib/postmark_client/models/email.rb', line 35

def from
  @from
end

#headers ⇒ Array<Hash>

Returns custom email headers.

Returns:

  • (Array<Hash>) —

    custom email headers



62
63
64
 
# File 'lib/postmark_client/models/email.rb', line 62

def headers
  @headers
end

#html_body ⇒ String?

Returns HTML email body.

Returns:

  • (String, nil) —

    HTML email body



50
51
52
 
# File 'lib/postmark_client/models/email.rb', line 50

def html_body
  @html_body
end

#message_stream ⇒ String

Returns message stream identifier.

Returns:

  • (String) —

    message stream identifier



77
78
79
 
# File 'lib/postmark_client/models/email.rb', line 77

def message_stream
  @message_stream
end

#metadata ⇒ Hash

Returns custom metadata key-value pairs.

Returns:

  • (Hash) —

    custom metadata key-value pairs



74
75
76
 
# File 'lib/postmark_client/models/email.rb', line 74

def metadata
  @metadata
end

#reply_to ⇒ String?

Returns reply-to email address.

Returns:

  • (String, nil) —

    reply-to email address



56
57
58
 
# File 'lib/postmark_client/models/email.rb', line 56

def reply_to
  @reply_to
end

#subject ⇒ String

Returns email subject.

Returns:

  • (String) —

    email subject



47
48
49
 
# File 'lib/postmark_client/models/email.rb', line 47

def subject
  @subject
end

#tag ⇒ String?

Returns email tag for categorization.

Returns:

  • (String, nil) —

    email tag for categorization



59
60
61
 
# File 'lib/postmark_client/models/email.rb', line 59

def tag
  @tag
end

#text_body ⇒ String?

Returns plain text email body.

Returns:

  • (String, nil) —

    plain text email body



53
54
55
 
# File 'lib/postmark_client/models/email.rb', line 53

def text_body
  @text_body
end

#to ⇒ String+

Returns recipient email address(es).

Returns:

  • (String, Array<String>) —

    recipient email address(es)



38
39
40
 
# File 'lib/postmark_client/models/email.rb', line 38

def to
  @to
end

#track_links ⇒ String

Returns link tracking setting (“None”, “HtmlAndText”, “HtmlOnly”, “TextOnly”).

Returns:

  • (String) —

    link tracking setting (“None”, “HtmlAndText”, “HtmlOnly”, “TextOnly”)



68
69
70
 
# File 'lib/postmark_client/models/email.rb', line 68

def track_links
  @track_links
end

#track_opens ⇒ Boolean

Returns whether to track email opens.

Returns:

  • (Boolean) —

    whether to track email opens



65
66
67
 
# File 'lib/postmark_client/models/email.rb', line 65

def track_opens
  @track_opens
end

Instance Method Details

#add_attachment(attachment) ⇒ self #add_attachment(name:, content:, content_type:, content_id: nil) ⇒ self

Add an attachment to the email

Overloads:

  • #add_attachment(attachment) ⇒ self

    Parameters:

    • attachment (Attachment) —

      an Attachment instance

  • #add_attachment(name:, content:, content_type:, content_id: nil) ⇒ self

    Parameters:

    • name (String) —

      filename

    • content (String) —

      file content

    • content_type (String) —

      MIME type

    • content_id (String, nil) (defaults to: nil) —

      content ID for inline attachments

Parameters:

  • attachment (Attachment) (defaults to: nil) —

    an Attachment instance

Returns:

  • (self) —

    returns self for method chaining



156
157
158
159
160
161
162
163
164
165
 
# File 'lib/postmark_client/models/email.rb', line 156

def add_attachment(attachment = nil, **kwargs)
  if attachment.is_a?(Attachment)
    @attachments << attachment
  elsif kwargs.any?
    @attachments << Attachment.new(**kwargs)
  else
    raise ArgumentError, "Must provide an Attachment instance or attachment parameters"
  end
  self
end

#add_header(name:, value:) ⇒ self

Add a custom header to the email

Parameters:

  • name (String) —

    header name

  • value (String) —

    header value

Returns:

  • (self) —

    returns self for method chaining



138
139
140
141
 
# File 'lib/postmark_client/models/email.rb', line 138

def add_header(name:, value:)
  @headers << { "Name" => name, "Value" => value }
  self
end

#add_metadata(key, value) ⇒ self

Add metadata to the email

Parameters:

  • key (String, Symbol) —

    metadata key

  • value (String) —

    metadata value

Returns:

  • (self) —

    returns self for method chaining



183
184
185
186
 
# File 'lib/postmark_client/models/email.rb', line 183

def add_metadata(key, value)
  @metadata[key.to_s] = value
  self
end

#attach_file(file_path, content_type: nil, content_id: nil) ⇒ self

Add a file as an attachment

Parameters:

  • file_path (String) —

    path to the file

  • content_type (String, nil) (defaults to: nil) —

    optional MIME type

  • content_id (String, nil) (defaults to: nil) —

    optional content ID

Returns:

  • (self) —

    returns self for method chaining



173
174
175
176
 
# File 'lib/postmark_client/models/email.rb', line 173

def attach_file(file_path, content_type: nil, content_id: nil)
  @attachments << Attachment.from_file(file_path, content_type: content_type, content_id: content_id)
  self
end

#to_h ⇒ Hash Also known as: to_api_hash

Convert the email to a hash for API requests

Returns:

  • (Hash) —

    the email as a hash matching Postmark API format



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/postmark_client/models/email.rb', line 217

def to_h
  hash = {}

  hash["From"] = from if from
  hash["To"] = normalize_recipients(to) if to
  hash["Cc"] = normalize_recipients(cc) if cc
  hash["Bcc"] = normalize_recipients(bcc) if bcc
  hash["Subject"] = subject if subject
  hash["HtmlBody"] = html_body if html_body
  hash["TextBody"] = text_body if text_body
  hash["ReplyTo"] = reply_to if reply_to
  hash["Tag"] = tag if tag
  hash["Headers"] = headers if headers.any?
  hash["TrackOpens"] = track_opens unless track_opens.nil?
  hash["TrackLinks"] = track_links if track_links
  hash["Attachments"] = attachments.map(&:to_h) if attachments.any?
  hash["Metadata"] = metadata if metadata.any?
  hash["MessageStream"] = message_stream if message_stream

  hash
end

#valid? ⇒ Boolean

Check if the email is valid

Returns:

  • (Boolean) —

    true if valid, false otherwise



207
208
209
210
211
212
 
# File 'lib/postmark_client/models/email.rb', line 207

def valid?
  validate!
  true
rescue ValidationError
  false
end

#validate! ⇒ Boolean

Validate the email before sending

Returns:

  • (Boolean) —

    true if valid

Raises:



192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/postmark_client/models/email.rb', line 192

def validate!
  raise ValidationError, "From address is required" if from.nil? || from.empty?
  raise ValidationError, "To address is required" if to.nil? || (to.is_a?(Array) && to.empty?) || (to.is_a?(String) && to.empty?)
  raise ValidationError, "Either HtmlBody or TextBody is required" if (html_body.nil? || html_body.empty?) && (text_body.nil? || text_body.empty?)

  if track_links && !TRACK_LINKS_OPTIONS.include?(track_links)
    raise ValidationError, "TrackLinks must be one of: #{TRACK_LINKS_OPTIONS.join(', ')}"
  end

  true
end