Skip to content

Email sending

Igor Balos edited this page Jun 20, 2022 · 24 revisions

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

To send a simple email, all you need is to create a mail message object, retrieve Postmark API client and send the message. You can validate the message by validating result of MessageResponse class.

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.

ApiClient client = Postmark.getApiClient(<server token>);

Deliver a simple message

String htmlBody = "<!DOCTYPE html><html><body>" +
"<p>Hello<a href=\"http://www.google.com\">world</a></p></body></html>";
        
// create a simple email message
Message message = new Message("from@example.com", "john@example.com", "Hello from Postmark!", htmlBody);
message.setReplyTo("support@example.com");

// Deliver a simple message
ApiClient client = Postmark.getApiClient(<server token>);
MessageResponse response = client.deliverMessage(message);
System.out.println(response.getMessage());

Sending a message with tag

Message message = new Message("from@example.com", "chris@example.com", "Hello from Postmark! with tag", "Hello body");
message.setTag("testTag");
client.deliverMessage(message);

Sending a message with custom from name

Message message = new Message("\"John & Smith, LLC\" from@example.com", "chris@example.com", "Hello from Postmark!", "Hello body");
client.deliverMessage(message);

Sending a message with metadata

Message message = new Message("from@example.com", "chris@example.com", "Hello from Postmark! with tag", "Hello body");

HashMap<String,String> metadata = new HashMap<String, String>();
metadata.put("test_field1","test_value");

message.setMetadata(metadata);
message.addMetadata("test_field2","test_value");

client.deliverMessage(message);

Sending a message with open tracking enabled

String htmlBody = "<!DOCTYPE html><html><body>" +
"<p>Hello<a href=\"http://www.google.com\">world</a></p></body></html>";

Message message = new Message("from@example.com", "chris@example.com", "Hello Postmark!", htmlBody);
message.setTrackOpens(true);
client.deliverMessage(message);

Sending a message with link tracking enabled

Setting up link tracking is easy. All you need to to is set the message to track links with setting tracking type to:

  • Html
  • Text
  • HtmlAndText

This will allow Postmark to track emails in text, html body of your message or both.

Message message = new Message("from@example.com", "chris@example.com", "Hello from Postmark!", htmlBody);
message.setTrackLinks(Message.TRACK_LINKS.HtmlAndText);
client.deliverMessage(message);

Sending a message with attachments

In order to send emails with attachments, all you need to do is specify a path where file you plan to attach can be found. Everything else will be handled by the library.

// Deliver message with attachments, parameter is file path
message = new Message("ibalosh@gmail.com", "natalie@example.com", "Hello from Postmark with attachment", "Hello body");
message.addAttachment("/Path/To/Your/File/file.pdf");
client.deliverMessage(message);

If you don't want to use files to add attachments, but rather add attachments on the fly, you could do one of the following.

If you want to use simple way with adding String content:

// Deliver message with attachments, parameter is HashMap of Name, Content and ContentType
message = new Message("igor@ActiveCampaign.com", "chris@example.com", "Hello from Postmark with attachment", "Hello body");

message.addAttachment("test.txt","text content will go here","application/text");
client.deliverMessage(message);

If you want to add Byte content:

// Deliver message with attachments - from bytes reading file
File file = new File("/Users/igor/test.pdf");
byte[] byteContent = new byte[(int) file.length()];
FileInputStream fis = new FileInputStream(file);
fis.read(byteContent);
fis.close();
        
message.addAttachment("test.pdf",byteContent,"application/pdf");

Or if you want to have full control of adding attachment:

// Deliver message with attachments, parameter is HashMap of Name, Content and ContentType
message = new Message("igor@ActiveCampaign.com", "chris@example.com", "Hello from Postmark with attachment", "Hello body");

HashMap<String,String> attachment = new HashMap<>();
attachment.put("Name", "filename.txt");
attachment.put("Content", Base64.getEncoder().encodeToString("test content".getBytes()));
attachment.put("ContentType", "text");

client.deliverMessage(message);

Sending a message with inline images

To send a message with inline images, the process is similar to the one when sending email with attachments. Only thing you will need to worry about is to add ContentId to the attachment images. Once you do that you will be able to reference in your html body to the image you added as attachment and show it inline.

Check the code example for details:

String htmlBody = "<!DOCTYPE html><html><body><p>Hello world <img src=\"cid:image.jpg\"/></a></p></body></html>";

Message message = new Message("igor@example.com", "john@example.com", "Hello there", htmlBody);
message.addAttachment("/Users/yourusername/Documents/Temp/yourImageFile.jpg");
Map<String,String> attachment = message.getAttachments().get(0);
attachment.put("ContentId", "cid:image.jpg");
client.deliverMessage(message);

Sending a message with custom headers

Library allows you to simply specify custom headers which you would like to be sent in your email message. Postmark library allows you to specify headers by either passing an Array of all your headers, or by simply adding to your message a key, value pair which identifies your custom header.

Check out the code example, which uses both options to add custom headers.

// create email message
Message message = new Message("from@example.com", "nick@example.com", "Hello from Postmark with custom headers", "Hello body");

// set headers
ArrayList<Header> headers = new ArrayList<>();
headers.add(new Header("TEST", "CUSTOM HEADER"));
message.setHeaders(headers);
message.addHeader("TEST2", "CUSTOM HEADER2");

// Deliver message with custom headers
client.deliverMessage(message);

Sending message to multiple recipients

Posmark Java library allows you to specify in detail to which recipients you want to send emails. It allows you to specify recipient type (To:, Cc:, Bcc:) , and to specify full name or recipients too. Let's checkout some examples how to set them up.

Sending email to recipients with full names included with email address:

// create email message
Message message = new Message("from@example.com", "andrew@example.com", "Hello from Postmark!", "Hello body");

// set recipients with full name by using Hash Maps
HashMap<String, String> to = new HashMap<>();
to.put("John Smith", "john@example.com");
to.put("Milan Gornik", "milan@example.com");

HashMap<String, String> cc = new HashMap<>();
cc.put("Andrew Teken", "andrew@example.com");

message.setTo(to);
message.setCc(cc);

// Deliver message with full name recipients
client.deliverMessage(message);

Sending email to array of recipient email addresses.

// create email message
Message message = new Message("from@example.com", "andrew@example.com", "Hello from Postmark!", "Hello body");

// set a simple list of recipients
ArrayList<String> to = new ArrayList<>();
to.add("derek@example.com");
to.add("matt@example.com");

message.setTo(to);

// Deliver message with array of recipients
client.deliverMessage(message);

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:

// create array of email messages
ArrayList<Message> messages = new ArrayList<>();
messages.add(new Message("from@example.com", "milan@example.com", "Hello from Postmark!", "Hello body"));
messages.add(new Message("from@example.com", "artem@example.com", "Hello from Postmark again!", "Hello body"));

// Deliver messages by batch
ArrayList<MessageResponse> responses = client.deliverMessage(messages);

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