Mailgun Java SDK

The Mailgun Java SDK enables Java developers to work with Mailgun API efficiently.

• Mailgun Home
• Mailgun API documentation
• Mailgun authentication documentation
• Base URL Documentation

Table of contents

• Release notes

• Getting Started

  • Requirements
  • Install the SDK
  • Authentication
  • Base URL
  • Domains

• Setup Client

  • Client Configuration

• Responses

• Exception handling

• Methods

• Testing

• Contribute

Release notes

Changes to the SDK beginning with version 1.0.1 (June 2022) are tracked in CHANGELOG.md.

Getting Started

Requirements

To run the SDK, you will need Java 1.8+.

Install the SDK

The recommended way to use the Mailgun Java SDK in your project:

Choose version you need

Maven.settings.xml

Add the following to your pom.xml:

<dependencies>
...
<dependency>
<groupId>com.mailgun</groupId>
<artifactId>mailgun-java</artifactId>
<version>2.4.2</version>
</dependency>
...
</dependencies>

Gradle Groovy DSL .

implementation 'com.mailgun:mailgun-java:2.4.2'

Authentication

When you Sign up, Mailgun generates a primary account API key.

To view your primary account API key in the Mailgun dashboard, click on Settings on the left-hand nav in the Mailgun dashboard and then API Keys and click on the eye icon next to API_KEYS.

Base URL

Mailgun allows sending and receiving an email in either our US or our EU regions.

Be sure to use the appropriate Base URL based on which region you've created your domain in.

For domains created in our US region, the base URL (DEFAULT_BASE_URL) is:

https://api.mailgun.net/

For domains created in our EU region, the base URL (EU_BASE_URL) is:

https://api.eu.mailgun.net/

Domains

Your Mailgun account may contain multiple sending domains.

Most API URLs must include the name of the domain you're interested in.

For example:

mailgunMessagesApi.sendMessage(YOUR_DOMAIN, message);

Setup Client

Client Configuration

Configuration examples

Default Mailgun Client configuration:

// For US serversMailgunClient.config(PRIVATE_API_KEY)
// For EU servers MailgunClient.config(EU_BASE_URL, PRIVATE_API_KEY)

Custom Mailgun client configuration.

You can specify your own logLevel, retryer, logger, errorDecoder, options.

MailgunClient.config(PRIVATE_API_KEY)
.logLevel(Logger.Level.NONE)
.retryer(newRetryer.Default())
.logger(newLogger.NoOpLogger())
.errorDecoder(newErrorDecoder.Default())
.options(newRequest.Options(10, TimeUnit.SECONDS, 60, TimeUnit.SECONDS, true))

Mailgun client configuration with request interceptor for all API calls

You can add your multiple custom:

1. request header in format: (headerName, headerValue)
2. form property with allowed prefixes such as: t:, o:, h:, v: with the followed by any arbitrary value.

MailgunMessagesApimailgunMessagesApi = MailgunClient.config(API_KEY)
.createApiWithRequestInterceptor(MailgunMessagesApi.class,
MailgunRequestInterceptor.builder()
.addHeader(HEADER_ON_BEHALF_OF, SUBACCOUNT_ACCOUNT_ID)
.addProperty("h:X-My-Header", "my_custom_header")
.build()
);

Mailgun client configuration example for the Mailgun sending emails API

MailgunMessagesApimailgunMessagesApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunMessagesApi.class);

Async Mailgun client configuration example for the Mailgun sending emails API

MailgunMessagesApimailgunAsyncMessagesApi = MailgunClient.config(PRIVATE_API_KEY)
.createAsyncApi(MailgunMessagesApi.class);

Spring Bean Mailgun client configuration example:

@BeanpublicMailgunMessagesApimailgunMessagesApi() {
returnMailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunMessagesApi.class);
}

Hint: register Mailgun API Client as a Singleton and reuse it while sending emails to reduce resource consumption

Responses

Each method that returns a specific JavaBean class is duplicated with the method with suffix ending with FeignResponse returns a Feign response.

You can use methods that return a specific JavaBean class:

MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(YOUR_DOMAIN, message);

Or FeignResponse:

ResponsefeignResponse = mailgunMessagesApi.sendMessageFeignResponse(YOUR_DOMAIN, message);

From FeignResponse you can get:

// status codeintstatusCode = feignResponse.status();
// HeadersMap<String, Collection<String>> headers = feignResponse.headers();
// Protocol versionRequest.ProtocolVersionprotocolVersion = feignResponse.protocolVersion();
// etc.

More information:

Feign HTTP Response

Feign Java client

But Feign does not have the functionality to deserialize responses out of the box.

To retrieves a JavaBean class from the FeignResponse you can use decode method:

MessageResponsemessageResponse = ObjectMapperUtil.decode(feignResponse, MessageResponse.class);

Or

JsonNodejsonNode = ObjectMapperUtil.decode(feignResponse, JsonNode.class);

Exception handling

FeignException - origin exception type for all HTTP Apis.

From FeignException you can get:

try {
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(YOUR_DOMAIN, message);
} catch (FeignExceptionexception) {
// Exception messageStringexceptionMessage = exception.getMessage();
// status code intstatusCode = exception.status();
// HeadersMap<String, Collection<String>> headers = exception.headers();
// etc.

More information: FeignException

Methods

Request examples

• Methods
  • Messages
    • Set up MailgunMessagesApi
    • Send email
    • Send email(name with email)
    • Send emails
    • Async send email(s)
    • Send email (html example)
    • Send email (attachments example)
    • Send email (attachment FormData example)
    • Send email (inline multiple files example)
    • Send email (delay example)
    • Send email (reply-to example)
    • Send email (mailing list example)
    • Send email (sender example)
    • Send email (with custom form property)
    • Send email(s) in MIME format
  • Store Messages
    • Set up MailgunStoreMessagesApi
    • Resend email(s)
    • Retrieve email
  • Domains
    • Set up MailgunDomainsApi
    • Get Domains list
    • Get single Domains
    • Verify Domain
    • Create Domain
    • Delete Domain
    • Create credentials
    • Update credentials
    • Get connection settings
    • Update connection settings
    • Get tracking settings
    • Update tracking settings
    • Update click tracking settings
    • Update unsubscribe tracking settings
  • IPs
    • Set up MailgunIPsApi
    • Get all IPs
    • Get dedicated IPs
    • Get specified IP
    • Get domain IP
    • Assign IP to domain
    • Unassign IP from domain
  • Events
    • Set up MailgunEventsApi
    • Get all Events
    • Get specified Events
    • Get Events next page
  • Stats
    • Set up MailgunStatisticsApi
    • Get domain Statistics
  • Tags
    • Set up MailgunTagsApi
    • Get all Tags
    • Get Tag
    • Update Tag
    • Get Tag statistics
    • Delete Tag
    • List Tag countries
    • List Tag providers
    • List Tag devices
  • Suppressions
    • Suppression Bounces
      • Set up MailgunSuppressionBouncesApi
      • Get Bounces
      • Get Bounce
      • Add Bounce
      • Add Bounces
      • Import Bounces
      • Delete Bounce
      • Delete all Bounces
    • Suppression Complaints
      • Set up MailgunSuppressionComplaintsApi
      • Get all Complaints
      • Get single Complaint
      • Add Address
      • Add Addresses
      • Import Addresses
      • Remove Address
    • Suppression Unsubscribe
      • Set up MailgunSuppressionUnsubscribeApi
      • Get all Unsubscribe
      • Get single Unsubscribe
      • Add address
      • Add addresses
      • Import addresses
      • Remove address tag
      • Remove address
    • Suppression Whitelists
      • Set up MailgunSuppressionWhitelistsApi
      • Get all Whitelists
      • Get single Whitelist
      • Add address/domain
      • Import address/domain
      • Delete address/domain
  • Routes
    • Set up MailgunRoutesApi
    • Get Routes list
    • Get single Route
    • Create Route
    • Update Route
    • Delete Route
  • Webhooks
    • Set up MailgunWebhooksApi
    • Get all Webhooks
    • Get Webhooks details
    • Create Webhook
    • Update Webhook
    • Delete Webhook
  • Mailing Lists
    • Set up MailgunMailingListApi
    • Get Mailing List
    • Get Mailing List by address
    • Create Mailing List
    • Update Mailing List
    • Delete Mailing List
    • Verify Mailing List members
    • Verification job status
    • Cancel verification job
    • List of members
    • Mailing List member
    • Add member
    • Update member
    • Add members
    • Delete member
  • Templates
    • Set up MailgunTemplatesApi
    • Get all Templates
    • Get all Templates(paging)
    • Get Template
    • Get Template Content
    • Create Template
    • Update Template
    • Delete Template
    • Delete all Templates
    • List Template stored versions
    • Get specified version Template Content
    • Create new Template version
    • Update Template version
    • Delete Template version
  • Email Validation/Verification
    • Set up MailgunEmailVerificationApi
    • Validate address
    • Get verification job list
    • Get verification job status
    • Create verification job
    • Cancel verification job
    • Get preview list
    • Check preview status
    • Create verification preview
    • Delete verification preview
  • [Inbox Placement](#Inbox Placement)
    • Set up MailgunSeedListApi
    • Generate seed list
    • Update seed list
    • Get seed lists
    • Get seed list
    • Get seed list attributes
    • Get seed list attribute
    • Get seed list filters
    • Delete seed list
    • Get list results
    • Get results filters
    • Get results attributes
    • Get results attribute
    • Get specific result
    • Delete result

Messages

MailgunMessagesApi allows you to send emails.

Mailgun Messages documentation.

When you submit messages for delivery, Mailgun places them in a message queue.

Set up MailgunMessagesApi

MailgunMessagesApimailgunMessagesApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunMessagesApi.class);

Send email

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(USER_EMAIL)
.subject(SUBJECT)
.text(TEXT)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (name with email)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EmailUtil.nameWithEmail(USER_NAME, USER_EMAIL))
.subject(SUBJECT)
.text(TEXT)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email(s)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(Arrays.asList(USER_EMAIL_1, USER_EMAIL_2))
.subject(SUBJECT)
.text(TEXT)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

or

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(USER_EMAIL_1)
.to(USER_EMAIL_2)
.subject(SUBJECT)
.text(TEXT)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Async send email(s)

Default Async Mailgun Client configuration:

MailgunMessagesApimailgunAsyncMessagesApi = MailgunClient.config(PRIVATE_API_KEY)
.client(asyncClient)
.createAsyncApi(MailgunMessagesApi.class);

Custom Async Mailgun Client configuration:

ExecutorServiceexecutor = Executors.newFixedThreadPool(2);
AsyncClient.Default<Object> asyncClient = newAsyncClient.Default<>(
newClient.Default(null, null), executor);
MailgunMessagesApimailgunAsyncMessagesApi = MailgunClient.config(PRIVATE_API_KEY)
.client(asyncClient)
.createAsyncApi(MailgunMessagesApi.class);

Your can create your own implementation of feign AsyncClient.

Asynchronously send email(s).

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(USER_EMAIL)
.subject(SUBJECT)
.text(TEXT)
.build();
CompletableFuture<MessageResponse> result = mailgunAsyncMessagesApi.sendMessageAsync(MAIN_DOMAIN, message);

Send email (html example)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.subject(SUBJECT)
.html("<html>\n" +
"<body>\n" +
"\t<h1>Sending HTML emails with Mailgun</h1>\n" +
"\t<p style=\"color:blue; font-size:30px;\">Hello world</p>\n" +
"\t<p style=\"font-size:30px;\">More examples can be found <a href=\"https://documentation.mailgun.com/en/latest/api-sending.html#examples\">here</a></p>\n" +
"</body>\n" +
"</html>")
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (attachments example)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.subject(SUBJECT)
.text(TEXT)
.attachment(newFile("/path/to/file_1"))
.attachment(newFile("/path/to/file-2"))
.attachment(Arrays.asList(newFile("/path/to/file_3"), newFile("/path/to/file_4")))
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (attachment FormData example)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.subject(SUBJECT)
.text(TEXT)
.formData(newFormData("image/png", "filename.png", pngByteArray))
.formData(newFormData("text/plain", "filename.txt", txtByteArray))
.formData(Arrays.asList(
newFormData("image/jpeg", "filename.jpeg", jpegByteArray),
newFormData("text/plain", "filename.txt", txtByteArray)
))
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (inline multiple files example)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.subject(SUBJECT)
.html("Text above images." +
"<div><img height=200 id=\"1\" src=\"cid:mailgun_logo.png\"/></div>" +
"Text between images." +
"<div><img id=\"2\" src=\"cid:test_images.jpeg\"/></div>" +
"Text below images.")
.inline(MAILGUN_LOGO_FILE)
.inline(TEST_IMAGES_FILE)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (delay example)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.subject(SUBJECT)
.text(TEXT)
.deliveryTime(ZonedDateTime.now().plusMinutes(2L)) // Two minutes delay.
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (reply-to example)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.subject(SUBJECT)
.text(TEXT)
.replyTo(REPLY_TO_EMAIL)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (mailing list example)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(MAILING_LIST_ADDRESS)
.subject(SUBJECT)
.text(TEXT)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (sender example)

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.sender(SENDER_EMAIL)
.subject(SUBJECT)
.text(TEXT)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

or sender with name and email

Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.sender(EmailUtil.nameWithEmail(SENDER_NAME, SENDER_EMAIL))
.subject(SUBJECT)
.text(TEXT)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send email (with custom form property)

You can send email(s) with your own custom dynamic form property with allowed prefixes such as: t:, o:, h:, v: with the followed by any arbitrary value.

MailgunMessagesApimailgunMessagesApi = MailgunClient.config(PRIVATE_API_KEY)
.createApiWithRequestInterceptor(MailgunMessagesApi.class,
MailgunRequestInterceptor.builder()
.addProperty("h:Sender", EmailUtil.nameWithEmail(SENDER_NAME, SENDER_EMAIL))
.addProperty("h:X-My-Header", "my_custom_header")
.build()
);
Messagemessage = Message.builder()
.from(EMAIL_FROM)
.to(EMAIL_TO)
.subject(SUBJECT)
.text(TEXT)
.build();
MessageResponsemessageResponse = mailgunMessagesApi.sendMessage(DOMAIN, message);

Send MIME email(s)

Send email(s) in MIME format

MailgunMimeMessagemailgunMimeMessage = MailgunMimeMessage.builder()
.to(EMAIL_TO)
.message(newFile("/path/to/file.mime"))
.build();
MessageResponseresult = mailgunMessagesApi.sendMIMEMessage(MAIN_DOMAIN, mailgunMimeMessage);

More examples - MailgunMessagesIntegrationTest

Store Messages

MailgunStoreMessagesApi allows you to work with stored messages.

Mailgun Store Messages documentation.

Set up MailgunStoreMessagesApi

MailgunStoreMessagesApimailgunStoreMessagesApi = MailgunClient.config(storedMessageUrl, PRIVATE_API_KEY)
.createApiWithAbsoluteUrl(MailgunStoreMessagesApi.class);

Resend email(s)

MessageResponseresult = mailgunStoreMessagesApi.resendMessage(EMAIL_TO);

Retrieve email(s)

StoreMessageResponseresult = mailgunStoreMessagesApi.retrieveMessage();

More examples - MailgunStoreMessagesIntegrationTest

Domains

MailgunDomainsApi allows you to create, access, and validate domains programmatically.

Mailgun Domains documentation.

Set up MailgunDomainsApi

MailgunDomainsApimailgunDomainsApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunDomainsApi.class);

Get Domains list

Returns a list of domains under your account (limit to 100 entries).

DomainListResponsedomainListResponse = mailgunDomainsApi.getDomainsList();

Get single Domains

Returns a single domain, including credentials and DNS records. Returns a list of domains under your account with filters.

SingleDomainResponsesingleDomainResponse = mailgunDomainsApi.getSingleDomain(DOMAIN);

Verify Domain

Verifies and returns a single domain, including credentials and DNS records.

If the domain is successfully verified, the domain's state will be active.

DomainResponsedomainResponse = mailgunDomainsApi.verifyDomain(DOMAIN);

For more information on verifying domains, visit Verifying domain documentation

Create Domain

Create a new domain.

DomainRequestrequest = DomainRequest.builder()
.name(DOMAIN_NAME)
.spamAction(SpamAction.BLOCK)
.wildcard(true)
.forceDkimAuthority(false)
.dkimKeySize(1024)
.ips(Arrays.asList(IP_1, IP_2))
.webScheme(WebScheme.HTTPS)
.build();
DomainResponsedomainResponse = mailgunDomainsApi.createNewDomain(request);

Delete Domain

Delete a domain from your account.

ResponseWithMessageresponse = mailgunDomainsApi.deleteDomain(DOMAIN_NAME);

Create credentials

Creates a new set of SMTP credentials for the defined domain.

DomainCredentialsdomainCredentials = DomainCredentials.builder()
.login(LOGIN)
.password(PASSWORD)
.build();
ResponseWithMessageresponse = mailgunDomainsApi.createNewCredentials(DOMAIN_NAME, domainCredentials);

Update credentials

Updates the specified SMTP credentials.

Currently, only the password can be changed.

ResponseWithMessageresponse = mailgunDomainsApi.updateCredentials(DOMAIN_NAME, LOGIN, PASSWORD);

Delete credentials

Deletes the defined SMTP credentials.

ResponseWithMessageresponse = mailgunDomainsApi.deleteCredentials(DOMAIN_NAME, LOGIN);

Get connection settings

Returns delivery connection settings for the defined domain.

DomainConnectionResponseresponse = mailgunDomainsApi.getDomainConnectionSettings(DOMAIN_NAME);

Update connection settings

Updates the specified delivery connection settings for the defined domain.

DomainConnectionRequestdomainConnection = DomainConnectionRequest.builder()
.requireTls(false)
.skipVerification(false)
.build();
UpdateDomainConnectionResponseresponse = mailgunDomainsApi.updateDomainConnectionSettings(DOMAIN_NAME, domainConnection);

Get tracking settings

Returns tracking settings for a domain.

DomainTrackingResponseresponse = mailgunDomainsApi.getDomainTrackingSettings(TEST_DOMAIN_NAME);

Update tracking settings

Updates the open tracking settings for a domain.

UpdateDomainOpenTrackingSettingsResponseresponse = mailgunDomainsApi.updateDomainOpenTrackingSettings(TEST_DOMAIN_NAME, YesNo.NO);

Update click tracking settings

Updates the click tracking settings for a domain.

UpdateDomainClickTrackingSettingsResponseresponse = mailgunDomainsApi.updateDomainClickTrackingSettings(TEST_DOMAIN_NAME, YesNoHtml.HTML_ONLY);

Update unsubscribe tracking settings

Updates unsubscribe tracking settings for a domain.

DomainUnsubscribeConnectionSettingsRequestrequest = DomainUnsubscribeConnectionSettingsRequest.builder()
.active(false)
.htmlFooter("\n<br>\n<p><a href=\\\"%unsubscribe_url%\\\">unsubscribe java</a></p>\n")
.textFooter("\n\nTo unsubscribe from java click: <%unsubscribe_url%>\n\n")
.build();
UpdateDomainUnsubscribeTrackingSettingsResponseresponse = mailgunDomainsApi.updateDomainUnsubscribeConnectionSettings(TEST_DOMAIN_NAME, request);

More examples - MailgunDomainsIntegrationTest

IPs

MailgunIPsApi allows you to access information regarding the IPs allocated to your Mailgun account used for outbound sending.

Mailgun IPs documentation.

Set up MailgunIPsApi

MailgunIPsApimailgunIPsApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunIPsApi.class);

Get all IPs

Returns a list of IPs assigned to your account.

IPsResultresult = mailgunIPsApi.getAllIPs();

Get dedicated IPs

Return only dedicated IPs if paramdedicated set to true, otherwise return all IPs.

IPsResultresult = mailgunIPsApi.getDedicatedIPs(true);

Get specified IP

Returns information about the specified IP.

IPResultresult = mailgunIPsApi.getSpecifiedIP(IP);

Get domain IP

Returns a list of IPs currently assigned to the specified domain.

IPsResultresult = mailgunIPsApi.getDomainIPs(DOMAIN);

Assign IP to domain

Assign a dedicated IP to the domain specified.

Note: Only dedicated IPs can be assigned to a domain.

ResponseWithMessageresponse = mailgunIPsApi.assignIPToDomain(DOMAIN, IP);

Unassign IP from domain

Unassign an IP from the domain specified.

ResponseWithMessageresponse = mailgunIPsApi.unassignIPFromDomain(DOMAIN, IP);

More examples - MailgunIPsIntegrationTest

Events

MailgunEventsApi Mailgun tracks every event that happens to your emails and makes this data available to you through the Events API.

Mailgun Events documentation.

Set up MailgunEventsApi

MailgunEventsApimailgunEventsApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunEventsApi.class);

Get all Events

Get all events that happen to your emails.

EventsResponseresponse = mailgunEventsApi.getAllEvents(DOMAIN);

Get specified Events

Get specified events that happen to your emails.

EventsQueryOptionseventsQueryOptions = EventsQueryOptions.builder()
.event(EventType.DELIVERED)
.build();
EventsResponseresponse = mailgunEventsApi.getEvents(DOMAIN, eventsQueryOptions);

Get Events next page

Fetches the next page of log records, assuming that the previous request returned the pageId.

EventsResponseresponse = mailgunEventsApi.getEvents(DOMAIN, pageId);

More examples - MailgunEventsIntegrationTest

Stats

MailgunStatisticsApi Mailgun collects many different events and generates event statistics available via this API.

Mailgun Statistics documentation.

Set up MailgunStatisticsApi

MailgunStatisticsApimailgunStatisticsApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunStatisticsApi.class);

Get domain Statistics

Returns total statistics for a given domain.

StatisticsOptionsstatsOptions = StatisticsOptions.builder()
.start(ZonedDateTime.now().minusDays(3))
.end(ZonedDateTime.now())
.event(Arrays.asList(StatsEventType.ACCEPTED, StatsEventType.DELIVERED))
.build();
StatsResultresult = mailgunStatisticsApi.getDomainStats(DOMAIN, statsOptions);

More examples - MailgunStatisticsIntegrationTest

Tags

MailgunTagsApi Mailgun lets you tag each outgoing message with a custom value and provides statistics on the tag level.

Mailgun Tags documentation.

Set up MailgunTagsApi

MailgunTagsApimailgunTagsApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunTagsApi.class);

Get all Tags

Returns a list of tags for a domain.

TagsResultresult = mailgunTagsApi.getAllTags(DOMAIN);

Get Tag

Returns a given tag.

TagsItemresult = mailgunTagsApi.getTag(DOMAIN, TAG);

Update Tag

Updates a given tag with the information provided.

TagUpdateRequestrequest = TagUpdateRequest.builder()
.description(newDescription)
.build();
ResponseWithMessageresponse = mailgunTagsApi.updateTag(DOMAIN, TAG, request);

Get Tag statistics

Returns statistics for a given tag.

StatisticsOptionsstatisticsOptions = StatisticsOptions.builder()
.event(Arrays.asList(StatsEventType.ACCEPTED, StatsEventType.DELIVERED))
.resolution(ResolutionPeriod.DAY)
.duration(3, Duration.DAY)
.build();
TagStatsResultresult = mailgunTagsApi.getTagStatistics(DOMAIN, TAG, statisticsOptions);

Delete Tag

Deletes the tag.

ResponseWithMessageresponse = mailgunTagsApi.deleteTag(DOMAIN, TAG);

List Tag countries

Returns a list of countries of origin for a given domain for different event types.

TagCountriesResponseresponse = mailgunTagsApi.listTagCountries(DOMAIN, TAG);

List Tag providers

Returns a list of email providers for a given domain for different event types.

TagProvidersResponseresponse = mailgunTagsApi.listTagProviders(DOMAIN, TAG);

List Tag devices

Returns a list of devices for a given domain that have triggered event types.

TagDevicesResponseresponse = mailgunTagsApi.listTagDevices(DOMAIN, TAG);

More examples - MailgunTagsApiIntegrationTest

Suppressions

Mailgun Suppressions documentation.

Suppression Bounces

MailgunSuppressionBouncesApi

Mailgun Suppression Bounces documentation.

Set up MailgunSuppressionBouncesApi

MailgunSuppressionBouncesApimailgunSuppressionBouncesApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunSuppressionBouncesApi.class);

Get Bounces

Returns a list of bounces for a domain.

BouncesResponseresponse = suppressionBouncesApi.getBounces(DOMAIN, MAXIMUM_NUMBER_OF_RECORDS);

Get Bounce

Fetch a single bounce event by a given email address.

Helpful to check if a given email address has bounced before.

BouncesItemresponse = suppressionBouncesApi.getBounce(DOMAIN, ADDRESS);

Add Bounce

Add a single bounce record to the bounce list.

Updates the existing record if the address is already there.

BouncesRequestbouncesRequest = BouncesRequest.builder()
.address(ADDRESS)
.code(CODE)
.error(ERROR_MESSAGE)
.createdAt(DATE_TIME)
.build();
SuppressionResponseresponse = suppressionBouncesApi.addBounce(DOMAIN, bouncesRequest);

Add Bounces

Add multiple bounce records to the bounce list in a single API call.

BouncesRequestbouncesRequest1 = BouncesRequest.builder()
.address(ADDRESS_1)
.code(CODE)
.error(ERROR_MESSAGE)
.createdAt(DATE_TIME)
.build();
BouncesRequestbouncesRequest2 = BouncesRequest.builder()
.address(ADDRESS_2)
.code(CODE)
.error(ERROR_MESSAGE)
.createdAt(DATE_TIME)
.build();
ResponseWithMessageresponse = suppressionBouncesApi.addBounces(DOMAIN, Arrays.asList(bouncesRequest1, bouncesRequest2));

Import Bounces

Import a list of bounces.

BouncesListImportRequestrequest = BouncesListImportRequest.builder()
.file(newFile("/path/to/file"))
.build();
ResponseWithMessageresult = suppressionBouncesApi.importBounceList(MAIN_DOMAIN, request);

Delete Bounce

Delete a single bounce.

ResponseWithMessageresponse = suppressionBouncesApi.deleteBounce(DOMAIN, ADDRESS);

Delete all Bounces

Delete all bounced email addresses for a domain.

ResponseWithMessageresponse = suppressionBouncesApi.deleteAllBounces(DOMAIN);

More examples - MailgunSuppressionBouncesApiIntegrationTest

Suppression Complaints

MailgunSuppressionComplaintsApi

Mailgun Suppression Complaints documentation.

Set up MailgunSuppressionComplaintsApi

MailgunSuppressionComplaintsApimailgunSuppressionComplaintsApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunSuppressionComplaintsApi.class);

Get all Complaints

Returns a list of complaints for a domain.

ComplaintsItemResponseresponse = suppressionComplaintsApi.getAllComplaints(DOMAIN, MAXIMUM_NUMBER_OF_RECORDS);

Get single Complaint

Fetch a single spam complaint by a given email address.

Helpful to check if a particular user has complained.

ComplaintsItemresponse = suppressionComplaintsApi.getSingleComplaint(DOMAIN, EMAIL);

Add Address

Add an address to the complaints list.

ComplaintsSingleItemRequestrequest = ComplaintsSingleItemRequest.builder()
.address(EMAIL)
.createdAt(DATE_TIME)
.build();
SuppressionResponseresponse = suppressionComplaintsApi.addAddressToComplaintsList(DOMAIN, request);

Add Addresses

Add multiple complaint records to the complaint list in a single API call(up to 1000 complaint records).

ComplaintsItemcomplaintsItem1 = ComplaintsItem.builder()
.address(EMAIL_1)
.createdAt(DATE_TIME)
.build();
ComplaintsItemcomplaintsItem2 = ComplaintsItem.builder()
.address(EMAIL_2)
.build();
ResponseWithMessageresponse = suppressionComplaintsApi.addAddressesToComplaintsList(MAIN_DOMAIN, Arrays.asList(complaintsItem1, complaintsItem2));

Import Addresses

Import a list of complaints.

ComplaintsListImportRequestrequest = ComplaintsListImportRequest.builder()
.file(newFile("/path/to/file"))
.build();
ResponseWithMessageresult = suppressionComplaintsApi.importComplaintsList(MAIN_DOMAIN, request);

Remove Address

Remove Address From Complaints.

SuppressionResponseresponse = suppressionComplaintsApi.removeAddressFromComplaints(DOMAIN, EMAIL);

More examples - MailgunSuppressionComplaintsApiIntegrationTest

Suppression Unsubscribe

MailgunSuppressionUnsubscribeApi

Mailgun Suppression Unsubscribe documentation.

Set up MailgunSuppressionUnsubscribeApi

MailgunSuppressionUnsubscribeApimailgunSuppressionUnsubscribeApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunSuppressionUnsubscribeApi.class);

Get all Unsubscribe

Returns a list of unsubscribes for a domain.

UnsubscribeItemResponseresponse = suppressionUnsubscribeApi.getAllUnsubscribe(DOMAIN, MAXIMUM_NUMBER_OF_RECORDS);

Get single Unsubscribe

Fetch a single unsubscribe record.

Can be used to check if a given address is present in the list of unsubscribed users.

UnsubscribeItemresponse = suppressionUnsubscribeApi.getSingleUnsubscribe(DOMAIN, EMAIL);

Add address

Add an address to the unsubscribe table.

UnsubscribeSingleItemRequestrequest = UnsubscribeSingleItemRequest.builder()
.address(EMAIL)
.tag(TAG)
.createdAt(DATE_TIME)
.build();
SuppressionResponseresponse = suppressionUnsubscribeApi.addAddressToUnsubscribeTable(DOMAIN, request);

Add addresses

Add multiple unsubscribe records to the unsubscribe list in a single API call(up to 1000 unsubscribe records).

UnsubscribeItemunsubscribeItemAllFields = UnsubscribeItem.builder()
.address(EMAIL_1)
.tags(Arrays.asList(TAG_1, TAG_2))
.createdAt(DATE_TIME)
.build();
UnsubscribeItemunsubscribeItemAddressOnly = UnsubscribeItem.builder()
.address(EMAIL_2)
.build();
ResponseWithMessageresponse = suppressionUnsubscribeApi.addAddressesToUnsubscribeTable(DOMAIN, Arrays.asList(unsubscribeItemAllFields, unsubscribeItemAddressOnly));

Import addresses

Import a CSV file containing a list of addresses to add to the unsubscribe list.

UnsubscribesListImportRequestrequest = UnsubscribesListImportRequest.builder()
.file(newFile("/path/to/file"))
.build();
ResponseWithMessageresult = suppressionUnsubscribeApi.importAddressesToUnsubscribeTable(MAIN_DOMAIN, request);

Remove address tag

Remove an address from the unsubscribes list.

SuppressionResponseresponse = suppressionUnsubscribeApi.removeAddressFromUnsubscribeTag(DOMAIN, EMAIL, TAG);

Remove address

Completely remove an address from the unsubscribes list.

SuppressionResponseresponse = suppressionUnsubscribeApi.removeAddressFromUnsubscribeList(DOMAIN, EMAIL);

More examples - MailgunSuppressionUnsubscribeApiIntegrationTest

Suppression Whitelists

MailgunSuppressionWhitelistsApi

Mailgun Suppression Whitelists documentation.

Set up MailgunSuppressionWhitelistsApi

MailgunSuppressionWhitelistsApimailgunSuppressionWhitelistsApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunSuppressionWhitelistsApi.class);

Get all Whitelists

Returns a list of whitelists for a domain.

WhitelistsItemResponseresponse = suppressionWhitelistsApi.getAllWhitelists(DOMAIN, MAXIMUM_NUMBER_OF_RECORDS);

Get single Whitelist

Fetch a single whitelist record.

Can be used to check if a given address or domain is present in the whitelist table.

WhitelistsItemresponse = suppressionWhitelistsApi.getSingleWhitelistRecord(DOMAIN, EMAIL);

Add address/domain

Add an address or domain to the whitelist table.

Note: The single request accepts either one address or domain parameter.

WhitelistsRequestrequest = WhitelistsRequest.builder()
.address(EMAIL)
.reason(REASON)
.build();
ResponseWithMessageresponse = suppressionWhitelistsApi.addSingleWhitelistRecord(DOMAIN, request);

Import address/domain

Import a CSV file containing a list of addresses and/or domains to add to the whitelist.

WhitelistsListImportRequestrequest = WhitelistsListImportRequest.builder()
.file(newFile("/path/to/file"))
.build();
ResponseWithMessageresult = suppressionWhitelistsApi.importWhitelistRecords(MAIN_DOMAIN, request);

Delete address/domain

Delete a single record from whitelist table.

WhitelistsRemoveRecordResponseresponse = suppressionWhitelistsApi.removeRecordFromWhitelists(DOMAIN, EMAIL);

More examples - MailgunSuppressionWhitelistsApiIntegrationTest

Routes

MailgunRoutesApi allows you to work with routes programmatically.

Mailgun Routes documentation.

Set up MailgunRoutesApi

MailgunRoutesApimailgunRoutesApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunRoutesApi.class);

Get Routes list

Fetches the list of routes.

RoutesPageRequestpageRequest = RoutesPageRequest.builder()
.limit(2)
.skip(2)
.build();
RoutesListResponseresponse = mailgunRoutesApi.getRoutesList(pageRequest);

Get single Route

Returns a single route object based on its ID.

SingleRouteResponseresponse = mailgunRoutesApi.getSingleRoute(ROUTE_ID);

Create Route

Creates a new route.

RoutesRequestroutesRequest = RoutesRequest.builder()
.priority(2)
.description(DESCRIPTION)
.expression("match_recipient('.*some-address-@example.com')")
.action("forward('" + EMAIL_2 + "')")
.action("forward('" + EMAIL_3 + "')")
.actions(Arrays.asList("forward('https://myhost.com/messages')", "stop()"))
.build();
RoutesResponseresponse = mailgunRoutesApi.createRoute(routesRequest);

Update Route

Updates a given route by ID.

RoutesRequestroutesRequest = RoutesRequest.builder()
.priority(1)
.action("forward('" + EMAIL + "')")
.build();
Routeresult = mailgunRoutesApi.updateRoute(routeId, routesRequest);

Delete Route

Deletes a route based on the id.

ResponseWithMessageresponse = mailgunRoutesApi.deleteRoute(ROUTE_ID);

More examples - MailgunRoutesIntegrationTest

Webhooks

MailgunWebhooksApi allows you to create, access, and delete webhooks programmatically.

Mailgun Webhooks documentation.

Set up MailgunWebhooksApi

MailgunWebhooksApimailgunWebhooksApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunWebhooksApi.class);

Get all Webhooks

Returns a list of webhooks set for the specified domain.

WebhookListResultresult = mailgunWebhooksApi.getAllWebhooks(DOMAIN);

Get Webhooks details

Return details about a webhook specified in the URL.

WebhookDetailsResultresult = mailgunWebhooksApi.getWebhookDetails(DOMAIN, WebhookName.CLICKED);

Create Webhook

Creates a new webhook.

WebhookRequestrequest = WebhookRequest.builder()
.webhookName(WebhookName.CLICKED)
.url(WEBHOOK_URL)
.build();
WebhookResultresult = mailgunWebhooksApi.createNewWebhook(DOMAIN, request);

Update Webhook

Updates an existing webhook.

WebhookUpdateRequestrequest = WebhookUpdateRequest.builder()
.urls(Arrays.asList(WEBHOOK_URL_2, WEBHOOK_URL_3))
.build();
WebhookResultresult = mailgunWebhooksApi.updateWebhook(MAIN_DOMAIN, WebhookName.CLICKED, request);

Delete Webhook

Deletes an existing webhook.

WebhookResultresult = mailgunWebhooksApi.deleteWebhook(DOMAIN, WebhookName.CLICKED);

More examples - MailgunWebhooksApiIntegrationTest

Mailing Lists

You can programmatically create mailing lists using MailgunMailingListApi

Mailgun Mailing Lists documentation.

Set up MailgunMailingListApi

MailgunMailingListApimailgunMailingListApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunMailingListApi.class);

Get Mailing List

Returns mailing lists under your account.

MailingListDataResponseresponse = mailgunMailingListApi.getMailingList(MAXIMUM_NUMBER_OF_RECORDS);

Get Mailing List by address

Returns a single mailing list by a given address.

SingleMailingListResponseresponse = mailgunMailingListApi.getMailingListByAddress(ADDRESS);

Create Mailing List

Creates a new mailing list.

MailingListRequestrequest = MailingListRequest.builder()
.address(MAILING_LIST_ADDRESS)
.name(MAILING_LIST_NAME)
.description(DESCRIPTION)
.accessLevel(AccessLevel.EVERYONE)
.replyPreference(ReplyPreference.LIST)
.build();
MailingListResponseresponse = mailgunMailingListApi.createMailingList(request);

Update Mailing List

Update mailing list properties, such as address, description or name.

UpdateMailingListRequestrequest = UpdateMailingListRequest.builder()
.address(NEW_ADDRESS)
.name(NEW_MAILING_LIST_NAME)
.description(NEW_DESCRIPTION)
.accessLevel(AccessLevel.MEMBERS)
.replyPreference(ReplyPreference.SENDER)
.build();
MailingListResponseresponse = mailgunMailingListApi.updateMailingList(MAILING_LIST_ADDRESS, request);

Delete Mailing List

Deletes a mailing list.

DeleteMailingListResponseresponse = mailgunMailingListApi.deleteMailingList(MAILING_LIST_ADDRESS);

Verify Mailing List members

Verify all the members of the mailing list.

MailingListVerificationResponseresponse = mailgunMailingListApi.verifyMailingListMembers(MAILING_LIST_ADDRESS);

Verification job status

Retrieve the current status of the mailing list verification job.

MailingListVerificationStatusResponseresponse = mailgunMailingListApi.getMailingListVerificationJobStatus(MAILING_LIST_ADDRESS);

Cancel verification job

Cancel an active mailing list verification job.

Stringresult = mailgunMailingListApi.cancelActiveMailingListVerificationJob(MAILING_LIST_ADDRESS);

List of members

Returns the list of members in the given mailing list.

MailingListMembersRequestrequest = MailingListMembersRequest.builder()
.limit(10)
.build();
MailingListMembersResponseresponse = mailgunMailingListApi.getMailingListMembers(MAILING_LIST_ADDRESS, request);

Returns the first page of the list of members in the given mailing list.

MailingListMembersRequestrequest = MailingListMembersRequest.builder()
.limit(10)
.page("first")
.build();
MailingListMembersResponseresponse = mailgunMailingListApi.getMailingListMembers(MAILING_LIST_ADDRESS, request);

Returns the last page of the list of members in the given mailing list.

MailingListMembersRequestrequest = MailingListMembersRequest.builder()
.limit(10)
.page("last")
.build();
MailingListMembersResponseresponse = mailgunMailingListApi.getMailingListMembers(MAILING_LIST_ADDRESS, request);

Returns the next page after specified email of the list of members in the given mailing list.

MailingListMembersResponseresponse = mailgunMailingListApi.getMailingListMembers(MAILING_LIST_ADDRESS, request);
memberAddress = response.getItems().stream()
.reduce((first, last) -> last)
.orElseThrow(NoSuchElementException::new)
.getAddress();
MailingListMembersRequestrequest = MailingListMembersRequest.builder()
.limit(10)
.page("next")
.address(memberAddress)
.build();
response = mailgunMailingListApi.getMailingListMembers(MAILING_LIST_ADDRESS, request);

Returns the previous page before specified email of the list of members in the given mailing list.

MailingListMembersResponseresponse = mailgunMailingListApi.getMailingListMembers(MAILING_LIST_ADDRESS, request);
memberAddress = response.getItems().stream()
.findFirst()
.orElseThrow(NoSuchElementException::new)
.getAddress();
MailingListMembersRequestrequest = MailingListMembersRequest.builder()
.limit(10)
.page("prev")
.address(memberAddress)
.build();
response = mailgunMailingListApi.getMailingListMembers(MAILING_LIST_ADDRESS, request);

Mailing List member

Retrieves a mailing list member.

MailingListMemberResponseresponse = mailgunMailingListApi.getMailingListMember(MAILING_LIST_ADDRESS, MEMBER_EMAIL);

Add member

Adds a member to the mailing list.

MailingListNewMemberRequestrequest = MailingListNewMemberRequest.builder()
.address(MEMBER_EMAIL)
.name(MEMBER_NAME)
.vars(MAP_OF_PARAMETERS)
.subscribed(true)
.build();
MailingListMemberResponseresponse = mailgunMailingListApi.addMemberToMailingList(MAILING_LIST_ADDRESS, request);

Update member

Updates a mailing list member with given properties. Won't touch the property if it's not passed in.

MailingListMemberUpdateRequestrequest = MailingListMemberUpdateRequest.builder()
.name(NEW_NAME)
.vars(MAP_OF_PARAMETERS)
.subscribed(true)
.build();
MailingListMemberResponseresponse = mailgunMailingListApi.updateMailingListMember(MAILING_LIST_ADDRESS, MEMBER_EMAIL, request);

Add members

Adds multiple members, up to 1,000 per call, to a Mailing List.

MailingListMembermailingListMember_1 = MailingListMember.builder()
.address(MEMBER_1_EMAIL)
.name(MEMBER_NAME)
.vars(MAP_OF_PARAMETERS)
.subscribed(true)
.build();
MailingListMembermailingListMember_2 = MailingListMember.builder()
.address(MEMBER_2_EMAIL)
.name(MEMBER_NAME)
.vars(MAP_OF_PARAMETERS)
.subscribed(false)
.build();
AddMailingListMembersRequestrequest = AddMailingListMembersRequest.builder()
.members(Arrays.asList(mailingListMember_1, mailingListMember_2))
.upsert(true)
.build();
MailingListResponseresponse = mailgunMailingListApi.addMembersToMailingList(MAILING_LIST_ADDRESS, request);

Delete member

Delete a mailing list member.

MailingListMemberResponseresponse = mailgunMailingListApi.deleteMemberFromMailingList(MAILING_LIST_ADDRESS, MEMBER_EMAIL);

More examples - MailgunMailingListApiIntegrationTest

Templates

MailgunTemplatesApi allows you to access information regarding the IPs allocated to your Mailgun account that is used for outbound sending.

Mailgun Templates documentation.

Set up MailgunTemplatesApi

MailgunTemplatesApimailgunTemplatesApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunTemplatesApi.class);

Get all Templates

Returns a list of stored templates for the domain (limit to 10 entries).

TemplatesResultresult = mailgunTemplatesApi.getAllTemplates(DOMAIN);

Get all Templates(paging)

Returns a list of stored templates for the domain with paging.

PagingWithPivotpagingWithPivot = PagingWithPivot.builder()
.limit(2)
.page(Page.NEXT)
.pivot(TEMPLATE_NAME)
.build();
TemplatesResultresult = mailgunTemplatesApi.getAllTemplates(MAIN_DOMAIN, pagingWithPivot);

Get Template

Returns metadata information about a stored template.

TemplateResponseresponse = mailgunTemplatesApi.getTemplate(DOMAIN, TEMPLATE_NAME);

Get Template Content

Returns the content of the active version of the template with metadata information.

TemplateWithVersionResponseresponse = mailgunTemplatesApi.getActiveTemplateVersionContent(DOMAIN, TEMPLATE_NAME);

Create Template

This API stores a new template, including its name, description, and (optionally) the template content.

If the template content is provided, a new version is automatically created and becomes the active version.

TemplateRequestrequest = TemplateRequest.builder()
.name(TEMPLATE_NAME)
.description(TEMPLATE_DESCRIPTION)
.template("Hey, {{name}}!")
.tag(TEMPLATE_VERSION_TAG)
.engine(TEMPLATE_ENGINE)
.comment(TEMPLATE_COMMENT)
.build();
TemplateWithMessageResponseresponse = mailgunTemplatesApi.storeNewTemplate(DOMAIN, request);

Update Template

Update the metadata information of the template.

TemplateStatusResponseresponse = mailgunTemplatesApi.updateTemplate(DOMAIN, TEMPLATE_NAME, TEMPLATE_DESCRIPTION);

Delete Template

Delete the template.

TemplateStatusResponseresponse = mailgunTemplatesApi.deleteTemplate(DOMAIN, TEMPLATE_NAME);

Delete all Templates

Delete all stored templates for the domain.

ResponseWithMessageresponse = mailgunTemplatesApi.deleteAllTemplatesInDomain(DOMAIN);

List Template stored versions

Returns a list of stored versions of the template.

TemplateAllVersionsResponseresponse = mailgunTemplatesApi.getAllTemplateVersions(DOMAIN, TEMPLATE_NAME);

Get specified version Template Content

Retrieve information and content of specified version of the template.

TemplateWithVersionResponseresponse = mailgunTemplatesApi.getSpecifiedVersionTemplateContent(DOMAIN, TEMPLATE_NAME, TEMPLATE_VERSION_TAG);

Create new Template version

Create a new version of a template.

If the template does not contain any other versions, the first version becomes active.

TemplateVersionRequestrequest = TemplateVersionRequest.builder()
.template(TEMPLATE)
.tag(TEMPLATE_VERSION_TAG)
.engine(TEMPLATE_ENGINE)
.comment(TEMPLATE_COMMENT)
.active(true)
.build();
TemplateWithMessageResponseresponse = mailgunTemplatesApi.createNewTemplateVersion(DOMAIN, TEMPLATE_NAME, request);

Update Template version

Update information or content of the specific version of the template.

UpdateTemplateVersionRequestrequest = UpdateTemplateVersionRequest.builder()
.template(TEMPLATE)
.comment(TEMPLATE_COMMENT)
.active(true)
.build();
TemplateVersionResponseresponse = mailgunTemplatesApi.updateSpecificTemplateVersion(DOMAIN, TEMPLATE_NAME, TEMPLATE_VERSION_TAG, request);

Delete Template version

Delete a specific version of the template.

TemplateVersionResponseresponse = mailgunTemplatesApi.deleteSpecificTemplateVersion(DOMAIN, TEMPLATE_NAME, TEMPLATE_VERSION_TAG);

More examples - MailgunTemplatesIntegrationTest

Email Validation/Verification

MailgunEmailVerificationApi is an email address verification service.

Mailgun Email Validation/Verification documentation.

Set up MailgunEmailVerificationApi

MailgunEmailVerificationApimailgunEmailVerificationApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunEmailVerificationApi.class);

Validate address

Given an arbitrary address, validates address based on defined checks.

AddressValidationResponseresult = mailgunEmailVerificationApi.validateAddress(EMAIL);

Get verification job list

Get list of all bulk verification jobs.

BulkVerificationJobListResponseresult = mailgunEmailVerificationApi.getBulkVerificationJobList();

Get verification job status

Check the current status of a bulk verification job.

BulkVerificationJobStatusResponseresult = mailgunEmailVerificationApi.getBulkVerificationJobStatus(LIST_NAME);

Create verification job

Create a bulk verification job.

BulkVerificationStatusRequestrequest = BulkVerificationStatusRequest.builder()
.file(newFile("/path/to/file"))
.build();
BulkVerificationCreatingResponseresult = mailgunEmailVerificationApi.createBulkVerificationJob(LIST_NAME, request);

Cancel verification job

Cancel current running bulk verification job.

Stringresult = mailgunEmailVerificationApi.cancelBulkVerificationJob(LIST_NAME);

Get preview list

Get list of all bulk verification previews.

BulkVerificationPreviewListResponseresult = mailgunEmailVerificationApi.getBulkVerificationPreviewList();

Check preview status

Check the current status of a bulk verification preview.

BulkVerificationPreviewResponseresult = mailgunEmailVerificationApi.getBulkVerificationPreviewStatus(LIST_NAME);

Create verification preview

Create a bulk verification preview.

BulkVerificationStatusRequestrequest = BulkVerificationStatusRequest.builder()
.file(newFile("/path/to/file"))
.build();
BulkVerificationCreatingResponseresult = mailgunEmailVerificationApi.createBulkVerificationPreview(LIST_NAME, request);

Delete verification preview

Delete a bulk verification preview.

Responseresult = mailgunEmailVerificationApi.deleteBulkVerificationPreview(LIST_NAME);

More examples - MailgunEmailVerificationIntegrationTest

Inbox Placement

MailgunSeedListApi A seed list is an object that provides the mailing list for your inbox placement test. It also acts as a container for all the results of those tests and will aggregate the stats of all the tests..

Inbox Placement documentation.

Set up MailgunSeedListApi

MailgunSeedListApimailgunSeedListApi = MailgunClient.config(PRIVATE_API_KEY)
.createApi(MailgunSeedListApi.class);

Generate seed list

Generate a seed list

SeedListRequestrequest = SeedListRequest.builder()
.seedFilter(SEED_FILTER)
.name(SEED_LIST_NAME)
.sendingDomains(Arrays.asList(TEST_DOMAIN_1, TEST_DOMAIN_2))
.build();
SeedListItemresult = mailgunSeedListApi.generateSeedList(request);

Update seed list

You can update a seed list with this endpoint.

SeedListRequestrequest = SeedListRequest.builder()
.seedFilter(SEED_FILTER)
.name(SEED_LIST_NAME)
.sendingDomains(Arrays.asList(TEST_DOMAIN_1, TEST_DOMAIN_2))
.build();
SeedListItemresult = mailgunSeedListApi.updateSeedList(TARGET_EMAIL, request);

Get seed lists

Get a list of all of your seed lists. You can filter this using the available filters.

SeedListsPageRequestfilter = SeedListsPageRequest.builder()
.limit(2)
.offset(1)
.ascending(false)
.build();
SeedListsResponseresult = mailgunSeedListApi.getAllSeedLists(filter);

Get seed list

You can select a single seed list with this endpoint.

SingleSeedListResponseresult = mailgunSeedListApi.getSeedList(TARGET_EMAIL);

Get seed list attributes

Get all iterable attributes of seed lists.

SeedListsAttributesResponseresult = mailgunSeedListApi.getSeedListsAttributes();

Get seed list attribute

Get all values of a specific attribute of your seed lists.

SeedListsAttributesResponseresult = mailgunSeedListApi.getSeedListsAttribute(ATTRIBUTE_NAME);

Get seed list filters

Get all available filters for seed lists.

SeedListsFiltersResponseresult = mailgunSeedListApi.getSeedListFilters();

Delete seed list

Delete a seed list.

Responseresult = mailgunSeedListApi.deleteSeedListFeignResponse(TARGET_EMAIL);

Get list results

Test results are generated when a message has been received at the target_email.

Responseresult = mailgunSeedListApi.getResultsFeignResponse();

Get results filters

Get Available Result Filters.

Responseresult = mailgunSeedListApi.getAvailableResultFiltersFeignResponse();

Get results attributes

Get all iterable attributes of results.

SeedListsAttributesResponseresult = mailgunSeedListApi.getResultsAttributes();

Get results attribute

Get all values of a specific attribute of your results lists.

SeedListsAttributesResponseresult = mailgunSeedListApi.getResultsAttribute(ATTRIBUTE);

Get specific result

Get a specific result.

Responseresult = mailgunSeedListApi.getSpecificResultFeignResponse(RID);

Delete result

Delete a result.

Responseresult = mailgunSeedListApi.deleteResultFeignResponse(RID);

More examples - MailgunSeedListIntegrationTest

Testing

WARNING - running the tests will cost you money!

To run the tests, various environment variables must be set:

• PRIVATE_API_KEY To view your primary account API key in the Mailgun dashboard, click on Settings on the left-hand nav in the Mailgun dashboard and then API Keys and click on the eye icon next to API_KEYS.
• MAIN_DOMAIN is the domain name - this is a value registered in the Mailgun admin interface or using MailgunDomainsApi.class.
• EMAIL_FROM is the email address used in various sending tests.
• EMAIL_TO is the email address used in various sending tests.

Run tests, including integration tests:

mvnverify -Pintegration-test

Run tests, excluding integration tests:

mvnverify

Contribute

Mailgun loves developers. You can be part of this project!

Feel free to ask anything, and contribute:

• Fork the project.
• Create a new branch.
• Implement your feature or bug fix.
• Add documentation for it.
• Add specs for your feature or bug fix.
• Commit and push your changes.
• Submit a pull request.

If you have suggestions on improving the guides, please submit an issue in our Official API Documentation repo.