com.mailgun.model.message.Message Maven / Gradle / Ivy
Show all versions of mailgun-java Show documentation
package com.mailgun.model.message;
import java.io.File;
import java.time.ZonedDateTime;
import java.util.List;
import java.util.Map;
import java.util.Set;
import com.mailgun.form.CustomProperties;
import org.apache.commons.collections4.CollectionUtils;
import org.apache.commons.lang3.StringUtils;
import com.mailgun.enums.YesNo;
import com.mailgun.enums.YesNoHtml;
import com.mailgun.util.CollectionUtil;
import com.mailgun.util.DateTimeUtil;
import com.mailgun.util.StringUtil;
import feign.form.FormData;
import feign.form.FormProperty;
import lombok.Builder;
import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.ToString;
import static com.mailgun.util.Constants.FIELD_CANNOT_BE_NULL_OR_EMPTY;
/**
* The object is used for sending messages(emails) using Mailgun API.
*
* @see field-explanation
*/
@Getter
@ToString
@EqualsAndHashCode
@Builder
public class Message {
/**
*
* Email address for From header.
*
*/
String from;
/**
*
* Email address of the recipient(s).
*
*/
Set to;
/**
*
* Same as {@link #to} but for Cc.
*
*/
Set cc;
/**
*
* Same as {@link #to} but for Bcc.
*
*/
Set bcc;
/**
*
* Message subject.
*
*/
String subject;
/**
*
* Body of the message. (text version)
*
*/
String text;
/**
*
* Body of the message. (HTML version)
*
*/
String html;
/**
*
* File attachment.
*
*
* You can post multiple attachment values.
*
*/
Set attachment;
/**
*
* File attachments in form of {@link FormData}.
* This object encapsulates a byte array and its associated content type.
*
*
* You can post multiple attachment values.
*
*/
@FormProperty("attachment")
Set formData;
/**
*
* Attachment with inline disposition.
*
*
* You can post multiple inline values.
*
*/
Set inline;
/**
*
* Name of a template stored via template API.
*
*/
String template;
/**
*
* Use this parameter to send a message to specific version of a template.
*
*/
@FormProperty("t:version")
String templateVersion;
/**
*
* Rendered template in the text part of the message in case of template sending.
*
*/
@FormProperty("t:text")
String renderTemplate;
/**
*
* Tag string.
*
*
* @see Tagging
*/
@FormProperty("o:tag")
Set tag;
/**
*
* Enables/disables DKIM signatures on per-message basis.
*
*/
@FormProperty("o:dkim")
String dkim;
/**
*
* Desired time of delivery.
*
*
*
* Note: Messages can be scheduled for a maximum of 3 days in the future.
*
*/
@FormProperty("o:deliverytime")
String deliveryTime;
/**
*
* Enables sending in test mode.
*
*
* @see Sending in Test Mode
*/
@FormProperty("o:testmode")
String testMode;
/**
*
* Toggles tracking on a per-message basis.
*
*
* @see Tracking Messages
*/
@FormProperty("o:tracking")
String tracking;
/**
*
* Toggles clicks tracking on a per-message basis.
*
*
* Has higher priority than domain-level setting.
*
*
* Pass TRUE, FALSE or HTML_ONLY
*
*/
@FormProperty("o:tracking-clicks")
String trackingClicks;
/**
*
* Toggles opens tracking on a per-message basis.
*
*
* Has higher priority than domain-level setting.
*
*/
@FormProperty("o:tracking-opens")
String trackingOpens;
/**
*
* If set to true, this requires the message only be sent over a TLS connection.
* If a TLS connection can not be established, Mailgun will not deliver the message.
*
* If set to false, Mailgun will still try and upgrade the connection,
* but if Mailgun can not, the message will be delivered over a plaintext SMTP connection.
*
* The default is false.
*
*/
@FormProperty("o:require-tls")
String requireTls;
/**
*
* If set to true, the certificate and hostname will not be verified when trying to establish a TLS connection
* and Mailgun will accept any certificate during delivery.
*
* If set to false, Mailgun will verify the certificate and hostname.
* If either one can not be verified, a TLS connection will not be established.
*
* The default is false.
*
*/
@FormProperty("o:skip-verification")
String skipVerification;
/**
*
* Specify Reply-To address
*
*/
@FormProperty("h:Reply-To")
String replyTo;
/**
*
* Specify Sender address
*
*/
@FormProperty("h:Sender")
String sender;
/**
*
* A valid JSON-encoded dictionary, where key is a plain recipient address and value is a dictionary
* with variables that can be referenced in the message body.
*
*
* @see Batch Sending
*/
@FormProperty("recipient-variables")
String recipientVariables;
/**
*
* Allows to attach a custom JSON data to the message
*
*/
@FormProperty("v:my-var")
String myVar;
/**
*
* Mailgun’s templates use a fork of the very popular template engine handlebars.
*
*
* Use this field to provide values for a substitution to render them in the template.
*
*/
@FormProperty("t:variables")
String mailgunVariables;
/**
*
* Specify custom email headers
*
*/
@CustomProperties(prefix = "h:")
Map headers;
public static MessageBuilder builder() {
return new CustomMessageBuilder();
}
private static class CustomMessageBuilder extends MessageBuilder {
public Message build() {
if (StringUtils.isBlank(super.from)) {
throw new IllegalArgumentException(String.format(FIELD_CANNOT_BE_NULL_OR_EMPTY, "from"));
}
if (CollectionUtils.isEmpty(super.to)) {
throw new IllegalArgumentException(String.format(FIELD_CANNOT_BE_NULL_OR_EMPTY, "to"));
}
super.to.stream()
.filter(StringUtils::isNotBlank)
.findFirst()
.orElseThrow(() -> new IllegalArgumentException(String.format(FIELD_CANNOT_BE_NULL_OR_EMPTY, "to")));
if (CollectionUtils.isNotEmpty(super.attachment) && CollectionUtils.isNotEmpty(super.formData)) {
throw new IllegalArgumentException("You cannot use 'attachment' and 'formData' together");
}
return super.build();
}
}
public static class MessageBuilder {
/**
*
* Email address of the recipient
*
*
* @param to Email address of the recipient
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder to(String to) {
this.to = CollectionUtil.addToSet(this.to, to);
return this;
}
/**
*
* Email addresses of the recipient
*
*
* @param to Email addresses of the recipient
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder to(List to) {
this.to = CollectionUtil.addToSet(this.to, to);
return this;
}
/**
*
* Same as {@link #to} but for Cc.
*
*
* @param cc Same as {@link #to} but for Cc.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder cc(String cc) {
this.cc = CollectionUtil.addToSet(this.cc, cc);
return this;
}
/**
*
* Same as {@link #to} but for Cc.
*
*
* @param cc Same as {@link #to} but for Cc.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder cc(List cc) {
this.cc = CollectionUtil.addToSet(this.cc, cc);
return this;
}
/**
*
* Same as {@link #to} but for Bcc.
*
*
* @param bcc Same as {@link #to} but for Bcc.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder bcc(String bcc) {
this.bcc = CollectionUtil.addToSet(this.bcc, bcc);
return this;
}
/**
*
* Same as {@link #to} but for Bcc.
*
*
* @param bcc Same as {@link #to} but for Bcc.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder bcc(List bcc) {
this.bcc = CollectionUtil.addToSet(this.bcc, bcc);
return this;
}
/**
*
* File attachment.
* You can post multiple attachment values.
*
*
* @param attachment File attachment
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder attachment(File attachment) {
this.attachment = CollectionUtil.addToSet(this.attachment, attachment);
return this;
}
/**
*
* File attachment.
* You can post multiple attachment values.
*
*
* @param attachments File attachments
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder attachment(List attachments) {
this.attachment = CollectionUtil.addToSet(this.attachment, attachments);
return this;
}
/**
*
* File attachment in form of {@link FormData}.
* This object encapsulates a byte array and its associated content type.
*
* You can post multiple attachment values.
*
* @param attachment attachment in form of {@link FormData}.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder formData(FormData attachment) {
this.formData = CollectionUtil.addToSet(this.formData, attachment);
return this;
}
/**
*
* File attachment in form of {@link FormData}.
* This object encapsulates a byte array and its associated content type.
*
* You can post multiple attachment values.
*
* @param attachments attachments in form of {@link FormData}.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder formData(List attachments) {
this.formData = CollectionUtil.addToSet(this.formData, attachments);
return this;
}
/**
*
* Attachment with inline disposition.
* You can post multiple inline values.
*
*
* @param attachment Attachment with inline disposition.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder inline(File attachment) {
this.inline = CollectionUtil.addToSet(this.inline, attachment);
return this;
}
/**
*
* Attachments with inline disposition.
* You can post multiple inline values.
*
*
* @param attachments Attachments with inline disposition.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public Message.MessageBuilder inline(List attachments) {
this.inline = CollectionUtil.addToSet(this.inline, attachments);
return this;
}
/**
*
* Rendered template in the text part of the message in case of template sending.
*
*
* @param renderTemplate Pass true if you want to have rendered template in the text part of the message in case of template sending.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder renderTemplate(boolean renderTemplate) {
if (renderTemplate) {
this.renderTemplate = YesNo.YES.getValue();
}
return this;
}
/**
*
* Tag string.
*
*
* @param tag Tag string.
* @return Returns a reference to this object so that method calls can be chained together.
* @see Tagging
*/
public Message.MessageBuilder tag(String tag) {
this.tag = CollectionUtil.addToSet(this.tag, tag);
return this;
}
/**
*
* Tag string.
*
*
* @param tags Tag strings.
* @return Returns a reference to this object so that method calls can be chained together.
* @see Tagging
*/
public Message.MessageBuilder tag(List tags) {
this.tag = CollectionUtil.addToSet(this.tag, tags);
return this;
}
/**
*
* Enables/disables DKIM signatures on per-message basis.
*
*
* @param enableDKIM Enables/disables DKIM signatures on per-message basis.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder dkim(boolean enableDKIM) {
this.dkim = YesNo.getValue(enableDKIM);
return this;
}
/**
*
* Desired time of delivery.
*
*
* Note: Messages can be scheduled for a maximum of 3 days in the future.
*
*
* @param deliveryTime Desired time of delivery.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder deliveryTime(ZonedDateTime deliveryTime) {
this.deliveryTime = DateTimeUtil.toString(deliveryTime);
return this;
}
/**
*
* Enables sending in test mode.
*
*
* @param enableSendingInTestMode Enables sending in test mode.
* @return Returns a reference to this object so that method calls can be chained together.
* @see Sending in Test Mode
*/
public MessageBuilder testMode(boolean enableSendingInTestMode) {
if (enableSendingInTestMode) {
this.testMode = YesNo.YES.getValue();
}
return this;
}
/**
*
* Toggles tracking on a per-message basis.
*
*
* @param toggleTracking Toggles tracking on a per-message basis.
* @return Returns a reference to this object so that method calls can be chained together.
* @see Tracking Messages
*/
public MessageBuilder tracking(boolean toggleTracking) {
this.tracking = YesNo.getValue(toggleTracking);
return this;
}
/**
*
* Toggles clicks tracking on a per-message basis.
* Has higher priority than domain-level setting.
*
*
* Pass TRUE, FALSE or HTML_ONLY
*
*
* @param yesNoHtml {@link YesNoHtml}
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder trackingClicks(YesNoHtml yesNoHtml) {
this.trackingClicks = yesNoHtml.getValue();
return this;
}
/**
*
* Toggles opens tracking on a per-message basis.
* Has higher priority than domain-level setting.
*
*
* @param toggleOpensTracking Toggles opens tracking on a per-message basis.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder trackingOpens(boolean toggleOpensTracking) {
this.trackingOpens = YesNo.getValue(toggleOpensTracking);
return this;
}
/**
*
* If set to true this requires the message only be sent over a TLS connection.
* If a TLS connection can not be established, Mailgun will not deliver the message.
*
* If set to false Mailgun will still try and upgrade the connection,
* but if Mailgun can not, the message will be delivered over a plaintext SMTP connection.
*
* The default is false.
*
*
* @param requireTLS requires TLS
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder requireTls(boolean requireTLS) {
this.requireTls = YesNo.getValue(requireTLS);
return this;
}
/**
*
* If set to true, the certificate and hostname will not be verified when trying to establish a TLS connection
* and Mailgun will accept any certificate during delivery.
*
* If set to false, Mailgun will verify the certificate and hostname.
* If either one can not be verified, a TLS connection will not be established.
*
* The default is false.
*
*
* @param skipVerification skip verification certificate and hostname
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder skipVerification(boolean skipVerification) {
this.skipVerification = YesNo.getValue(skipVerification);
return this;
}
/**
*
* Specify Reply-To address
*
*
* @param replyTo Reply-To address
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder replyTo(String replyTo) {
this.replyTo = replyTo;
return this;
}
/**
*
* Specify Sender address
*
*
* @param sender Sender address
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder sender(String sender) {
this.sender = sender;
return this;
}
/**
*
* A dictionary, where the key is a plain recipient address
* and the value is a dictionary with variables that can be referenced in the message body.
*
*
* @param recipientVariables A dictionary, where the key is a plain recipient address
* and the value is a dictionary with variables that can be referenced in the message body.
* @return Returns a reference to this object so that method calls can be chained together.
* @see Batch Sending
*/
public MessageBuilder recipientVariables(Map recipientVariables) {
this.recipientVariables = StringUtil.asJsonString(recipientVariables);
return this;
}
/**
*
* A dictionary, where the key is a plain recipient address
* and the value is a dictionary with variables that can be referenced in the message body.
*
*
* @param recipientVariables A valid JSON-encoded dictionary, where the key is a plain recipient address
* and the value is a dictionary with variables that can be referenced in the message body.
* @return Returns a reference to this object so that method calls can be chained together.
* @see Batch Sending
*/
public MessageBuilder recipientVariables(String recipientVariables) {
this.recipientVariables = recipientVariables;
return this;
}
/**
*
* Allows to attach a custom data to the message
*
*
* @param myVar dictionary
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder myVar(Map myVar) {
this.myVar = StringUtil.asJsonString(myVar);
return this;
}
/**
*
* Allows to attach a custom data to the message
*
*
* @param myVar A valid JSON-encoded dictionary
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder myVar(String myVar) {
this.myVar = myVar;
return this;
}
/**
*
* Mailgun’s templates use a fork of the very popular template engine handlebars.
*
*
* Use this field to provide values for a substitution to render them in the template.
*
*
* @param mailgunVariables A dictionary where the key is a placeholder and the value is a value for a substitution.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder mailgunVariables(Map mailgunVariables) {
this.mailgunVariables = StringUtil.asJsonString(mailgunVariables);
return this;
}
/**
*
* Mailgun’s templates use a fork of the very popular template engine handlebars.
*
*
* Use this field to provide values for a substitution to render them in the template.
*
*
* @param mailgunVariables A valid JSON-encoded dictionary, where the key is a placeholder and
* the value is a value for a substitution.
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder mailgunVariables(String mailgunVariables) {
this.mailgunVariables = mailgunVariables;
return this;
}
/**
*
* Specify custom email headers
*
*
* @param headers custom email headers
* @return Returns a reference to this object so that method calls can be chained together.
*/
public MessageBuilder headers(Map headers) {
this.headers = headers;
return this;
}
}
}