Email sending

With Postmark you can send email messages very easy. Before diving into this chapter, make sure you have checked out our getting started page.

To send a simple email, all you need to do is create Postmark API client and send a mail message.

For these API requests you will need to use a server API token. Once you obtain it, you will need to use server API client.

server_token = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
client = Postmark::ApiClient.new(server_token, http_open_timeout: 15)

Sending a simple email

Check out the code below to see how to send a simple plain text email message.

client.deliver(from: '[email protected]',
               to: 'Leonard Hofstadter <[email protected]>',
               subject: 'Re: Come on, Sheldon. It will be fun.',
               text_body: 'That\'s what you said about the Green Lantern.')

# => {:to=>"Leonard Hofstadter <[email protected]>", :submitted_at=>"2013-05-09T02:45:16.2059023-04:00", :message_id=>"b2b268e3-6a70-xxxx-b897-49c9eb8b1d2e", :error_code=>0, :message=>"OK"}

Sending an email with tag

You can categorize outgoing email using the optional :tag property. If you use different tags for the different types of emails your application generates, you will be able to get detailed statistics for them through the Postmark user interface.

client.deliver(from: '[email protected]',
               to: 'Penny <[email protected]>',
               subject: 'Re: You cleaned my apartment???',
               text_body: 'I couldn\'t sleep!',
               tag: 'confidential')

# => {:to=>"Penny <[email protected]>", :submitted_at=>"2013-05-09T03:00:55.4454938-04:00", :message_id=>"34aed4b3-3a95-xxxx-bd1d-88064909cc93", :error_code=>0, :message=>"OK"}

Sending a simple email to custom message stream

Check out the code below to see how to send a simple plain text email message.

client.deliver(from: '[email protected]',
               to: 'Leonard Hofstadter <[email protected]>',
               subject: 'Re: Come on, Sheldon. It will be fun.',
               text_body: 'That\'s what you said about the Green Lantern.',
               message_stream: 'outbound'
)

# => {:to=>"Leonard Hofstadter <[email protected]>", :submitted_at=>"2013-05-09T02:45:16.2059023-04:00", :message_id=>"b2b268e3-6a70-xxxx-b897-49c9eb8b1d2e", :error_code=>0, :message=>"OK"}

Sending an email with custom headers

Check out the code below to see how to send a simple plain text email message.

client.deliver(from: '[email protected]',
               to: 'Leonard Hofstadter <[email protected]>',
               subject: 'Re: Come on, Sheldon. It will be fun.',
               text_body: 'That\'s what you said about the Green Lantern.',
               headers: [
                    {name: "Header1", value: "Value1"},
                    {name: 'Header2', value: 'Value2'}
                ])

# => {:to=>"Leonard Hofstadter <[email protected]>", :submitted_at=>"2019-05-09T02:45:16.2059023-04:00", :message_id=>"b21268e3-6a70-xxxx-b897-49c9eb8b1d2e", :error_code=>0, :message=>"OK"}

Sending a message with custom headers

message = Mail.new do
  from            '[email protected]'
  to              'Dr. Sheldon Cooper <[email protected]>'
  subject         'Have you seen these pictures of yours?'
  body            'You look like a real geek!'
  add_file        '1.jpeg'

  delivery_method Mail::Postmark, :api_token => 'server token'
end

message['Header1'] = 'Value1'

message.deliver

# => #<Mail::Message:70185826686240, Multipart: true, Headers: <From: [email protected]>, <To: [email protected]>, <Message-ID: b1644cc1-b5b1-4bcb-aaf8-2f290b5aad80>, <Subject: Have you seen these pictures of yours?>, <Content-Type: multipart/mixed; boundary=--==_mimepart_5121f9f1ec653_12c53fd569035ad817726>>

Sending a message with metadata

To send metadata with email messages you send, all you need to do is provide metadata for your messages in form of a hash map. Metadata can provide better and more advanced filtering and categorizing of your messages.

message = Mail.new do
  from            '[email protected]'
  to              'Dr. Sheldon Cooper <[email protected]>'
  subject         'Have you seen these pictures of yours?'
  body            'You look like a real geek!'
  add_file        '1.jpeg'
  metadata        {"Example1"=>"value","Example2"=>"value"}

  delivery_method Mail::Postmark, :api_token => 'server token'
end

message.deliver

# => #<Mail::Message:70185826686240, Multipart: true, Headers: <From: [email protected]>, <To: [email protected]>, <Message-ID: ba644cc1-b5b1-4bcb-aaf8-2f290b5aad80>, <Subject: Have you seen these pictures of yours?>, <Content-Type: multipart/mixed; boundary=--==_mimepart_5121f9f1ec653_12c53fd569035ad817726>>

Please notice that in this case Mail library was used to compose the message. To find out more about this feature, check out the following guide.

Sending a message with open tracking enabled

Simply pass an HTML document as html_body parameter to #deliver. You can also enable open tracking by setting track_opens to true.

client.deliver(from: '[email protected]',
               to: 'Leonard Hofstadter <[email protected]>',
               subject: 'Re: What, to you, is a large crowd?',
               html_body: '<p>Any group big enough to trample me to death. ' \
                          'General rule of thumb is 36 adults or 70 ' \
                          'children.</p>',
               track_opens: true)

# => {:to=>"Leonard Hofstadter <[email protected]>", :submitted_at=>"2013-05-09T02:51:08.8789433-04:00", :message_id=>"75c28987-564e-xxxx-b6eb-e8071873ac06", :error_code=>0, :message=>"OK"}

Sending a message with link tracking enabled

To track visited links for emails you send, make sure to have links in html body, text body or both of the email you plan to send. You need to enable link tracking by setting track_links parameter to one of the following options: :html_only, :text_only, :html_and_text or :none.

Depending on parameter you set, link tracking will be enabled on plain text body, html body, both or none. Optionally you can also use string values as parameters 'HtmlOnly', 'TextOnly', 'HtmlAndText' or 'None'.

Notice that we set track_links field to :html_and_text, to enable link tracking for both plain text and html parts for this message.

message = Mail.new do
  from            '[email protected]'
  to              'Leonard Hofstadter <[email protected]>'
  subject         'Re: What, to you, is a large crowd?'

  text_part do
    body          'Any group big enough to trample me to death. General rule of thumb is 36 adults or 70 children - http://www.example.com.'
  end

  html_part do
    content_type  'text/html; charset=UTF-8'
    body          '<p>Any group big enough to trample me to death. ' \
                  'General <a href="http://www.example.com">rule of thumb</a> is 36 adults or 70 ' \
                  'children.</p>'
  end

  track_links     :html_and_text

  delivery_method Mail::Postmark, :api_token => 'server token'
end

message.deliver

# => #<Mail::Message:70355902117460, Multipart: true, Headers: <From: [email protected]>, <To: [email protected]>, <Message-ID: 1a1370a1-6c21-4304-a03c-320a54cc59f7>, <Subject: Re: What, to you, is a large crowd?>, <Content-Type: multipart/alternative; boundary=--==_mimepart_58380d6029b17_20543fd48543fa14977a>, <TRACK-LINKS: HtmlAndText>>

Sending a message with attachments

You can add attachments to messages you send. Keep in mind attachment size is limited to 10Mb.

message = Mail.new do
  from            '[email protected]'
  to              'Dr. Sheldon Cooper <[email protected]>'
  subject         'Have you seen these pictures of yours?'
  body            'You look like a real geek!'

  delivery_method Mail::Postmark, :api_token => 'server token'
end

message.attachments['sheldon.jpeg'] = File.read('2.jpeg')
message.deliver

# => #<Mail::Message:70185826686240, Multipart: true, Headers: <From: [email protected]>, <To: [email protected]>, <Message-ID: ba644cc1-b5b1-4bcb-aaf8-2f290b5aad80>, <Subject: Have you seen these pictures of yours?>, <Content-Type: multipart/mixed; boundary=--==_mimepart_5121f9f1ec653_12c53fd569035ad817726>>

You can also make an attachment inline:

message.attachments.inline['sheldon.jpeg'] = File.read('2.jpeg')

Then simply use Mail::Part#url method to reference it from your email body.

<p><img src="<%= message.attachments['sheldon.jpeg'].url %>" alt="Dr. Sheldon Cooper"></p>

For inline attachments it is possible to specify content IDs via the content_id attribute.

client.deliver(from: '[email protected]',
               to: 'Dr. Sheldon Cooper <[email protected]>',
               subject: 'Have you seen these pictures of yours?',
               text_body: 'You look like a real geek!',
               html_body: '<p>You look like a real geek!</p><center><img src="cid:42"></center>',
               attachments: [File.open('1.jpeg'),
                             {name: 'sheldon.jpeg',
                              content: [File.read('2.jpeg')].pack('m'),
                              content_type: 'image/jpeg'},
                             {name: 'logo.png',
                              content: [File.read('1.png')].pack('m'),
                              content_type: 'image/png',
                              content_id: 'cid:42'}])

# => {:to=>"Dr. Sheldon Cooper <[email protected]>", :submitted_at=>"2013-05-09T02:56:12.2828813-04:00", :message_id=>"8ec0d283-8b93-xxxx-9d65-241d1777cf0f", :error_code=>0, :message=>"OK"}

Sending a multipart message

client.deliver(from: '[email protected]',
               to: 'Leonard Hofstadter <[email protected]>',
               subject: 'Re: Anything Can Happen Thursday',
               text_body: 'Apparently the news didn\'t reach my digestive ' \
                          'system, which when startled has it\'s own version ' \
                          'of "Anything Can Happen Thursday"',
               html_body: '<p>Apparently the news didn&rsquo;t reach my ' \
                          'digestive system, which when startled has ' \
                          'it&rsquo;s own version of &ldquo;Anything Can '\
                          'Happen Thursday&rdquo;</p>')

# => {:to=>"Leonard Hofstadter <[email protected]>", :submitted_at=>"2013-05-09T02:58:00.089828-04:00", :message_id=>"bc973458-1315-xxxx-b295-6aa0a2b631ac", :error_code=>0, :message=>"OK"}

Sending to multiple recipients

You can pass multiple recipient addresses in the :to field and the optional :cc and :bcc fields. Note that Postmark has a limit of 50 recipients per message in total. You need to take care not to exceed that limit. Otherwise, you will get an error.

client.deliver(from: '[email protected]',
               to: ['Leonard Hofstadter <[email protected]>',
                    'Penny <[email protected]>'],
               cc: ['Dr. Koothrappali <[email protected]>'],
               bcc: '[email protected]',
               subject: 'Re: Come on, Sheldon. It will be fun.',
               text_body: 'That\'s what you said about the Green Lantern ' \
                          'movie. You were 114 minutes of wrong.')

# => {:to=>"Leonard Hofstadter <[email protected]>, Penny <[email protected]>", :submitted_at=>"2013-05-09T05:04:16.3247488-04:00", :message_id=>"d647c5d6-xxxx-466d-9411-557dcd5c2297", :error_code=>0, :message=>"OK"}

Deliver email in batches

Sometimes you would like to send many emails at once. Postmark allows you to do that by sending array of emails in batches. In order to do that, check out the following code example:

messages = []

messages << {from: '[email protected]',
             to: 'Leonard Hofstadter <[email protected]>',
             subject: 'Re: Come on, Sheldon. It will be fun.',
             text_body: 'That\'s what you said about the Green Lantern ' \
                        'movie. You were 114 minutes of wrong.'}

messages << {from: '[email protected]',
             to: 'Penny <[email protected]>',
             subject: 'Re: You cleaned my apartment???',
             text_body: 'I couldn\'t sleep knowing that just outside my ' \
                        'bedroom is our living room and just outside our ' \
                        'living room is that hallway and immediately ' \
                        'adjacent to that hallway is this!',
             tag: 'confidential'}

response = client.deliver_in_batches(messages)

# => [{:to=>"Leonard Hofstadter <[email protected]>", :submitted_at=>"2013-05-09T05:19:16.3361118-04:00", :message_id=>"247e43a9-6b0d-4914-a87f-7b74bf76b5cb", :error_code=>0, :message=>"OK"}, {:to=>"Penny <[email protected]>", :submitted_at=>"2013-05-09T05:19:16.3517099-04:00", :message_id=>"26467642-f169-4da8-87a8-b89154067dfb", :error_code=>0, :message=>"OK"}]

After delivering a batch you can check on each message’s delivery status:

response.first.delivered?
# => true

response.all?(&:delivered)
# => true

Please note that the delivering email in batches will return a 200-level HTTP status, even when validation for individual messages may fail - like bounced messages. Users of this endpoint should check the response for each message in the response from our API.