Skip to content

Commit 4a081a0

Browse files
committed
MT-22401: Add Email Campaigns API
Implement the six Email Campaigns operations (list, create, get, update, delete, stats) against the token-scoped /api/email_campaigns URL family. - New MailtrapEmailCampaignsApi grouping (fresh URL family, not account-scoped); wired through the factory and MailtrapClient (Lombok constructor updated). - DTOs: bare EmailCampaign + EmailCampaignListResponse {data, pagination} for list only; bare EmailCampaign for create/get/update/delete; bare EmailCampaignStats (defined once, reused inline). Request bodies wrap under email_campaign; partial PATCH via @builder + @JsonInclude(NON_NULL). - DeliveryMode + CampaignState enums under model/ with all spec values. - scheduled_for forced to ISO-8601 via @jsonformat (mapper would otherwise emit a numeric timestamp the API rejects). - EmailCampaignsImplTest + fixtures, example, README entry.
1 parent 6a6e43b commit 4a081a0

31 files changed

Lines changed: 1244 additions & 1 deletion

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -378,6 +378,10 @@ You can find the [Mailtrap Java API reference](https://mailtrap.github.io/mailtr
378378

379379
- [Email Templates](examples/java/io/mailtrap/examples/emailtemplates/EmailTemplatesExample.java)
380380

381+
### Email Marketing API
382+
383+
- [Email Campaigns](examples/java/io/mailtrap/examples/emailcampaigns/EmailCampaignsExample.java)
384+
381385
## Contributing
382386

383387
Bug reports and pull requests are welcome on [GitHub](https://github.com/mailtrap/mailtrap-java). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
package io.mailtrap.examples.emailcampaigns;
2+
3+
import io.mailtrap.config.MailtrapConfig;
4+
import io.mailtrap.factory.MailtrapClientFactory;
5+
import io.mailtrap.model.DeliveryMode;
6+
import io.mailtrap.model.request.emailcampaigns.CreateEmailCampaign;
7+
import io.mailtrap.model.request.emailcampaigns.CreateEmailCampaignRequest;
8+
import io.mailtrap.model.request.emailcampaigns.TemplateAttributes;
9+
import io.mailtrap.model.request.emailcampaigns.UpdateEmailCampaign;
10+
import io.mailtrap.model.request.emailcampaigns.UpdateEmailCampaignRequest;
11+
import io.mailtrap.model.response.emailcampaigns.DeliveryOptions;
12+
import io.mailtrap.model.response.emailcampaigns.ReplyTo;
13+
14+
import java.time.OffsetDateTime;
15+
import java.time.ZoneOffset;
16+
17+
public class EmailCampaignsExample {
18+
19+
private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
20+
// ID of a verified sending domain on the account.
21+
private static final long MAILSEND_DOMAIN_ID = 123L;
22+
23+
public static void main(String[] args) {
24+
final var config = new MailtrapConfig.Builder()
25+
.token(TOKEN)
26+
.build();
27+
28+
final var client = MailtrapClientFactory.createMailtrapClient(config);
29+
30+
// The campaign endpoints are token-scoped: the account is resolved from the API token.
31+
final var campaigns = client.emailCampaignsApi().emailCampaigns();
32+
33+
// List campaigns (newest first). `search` filters by name; `token` is the page number.
34+
final var page = campaigns.getEmailCampaigns(50, "Spring", 1);
35+
System.out.println(page);
36+
37+
// Create a campaign — it starts in the `draft` state.
38+
final var createRequest = new CreateEmailCampaignRequest(
39+
CreateEmailCampaign.builder()
40+
.name("Spring Sale")
41+
.mailsendDomainId(MAILSEND_DOMAIN_ID)
42+
.fromDisplayName("Acme Marketing")
43+
.fromLocalPart("news")
44+
.replyTo(ReplyTo.builder()
45+
.displayName("Acme Support")
46+
.localPart("support")
47+
.domain("acme.com")
48+
.build())
49+
.templateAttributes(TemplateAttributes.builder()
50+
.subject("Spring is here — 30% off")
51+
.build())
52+
.build());
53+
54+
final var created = campaigns.createEmailCampaign(createRequest);
55+
System.out.println(created);
56+
57+
final var campaignId = created.getId();
58+
59+
// Retrieve a single campaign.
60+
final var fetched = campaigns.getEmailCampaign(campaignId);
61+
System.out.println(fetched);
62+
63+
// Update is a PATCH — only the provided fields change. Schedule it for later and pass the
64+
// existing template id to update the subject in place.
65+
final var updateRequest = new UpdateEmailCampaignRequest(
66+
UpdateEmailCampaign.builder()
67+
.name("Spring Sale (updated)")
68+
.deliveryMode(DeliveryMode.SCHEDULED)
69+
.scheduledFor(OffsetDateTime.of(2026, 6, 1, 9, 0, 0, 0, ZoneOffset.UTC))
70+
.deliveryOptions(DeliveryOptions.builder().emailsPerHour(1000).build())
71+
.templateAttributes(TemplateAttributes.builder()
72+
.id(fetched.getTemplate().getId())
73+
.subject("New subject")
74+
.build())
75+
.build());
76+
77+
final var updated = campaigns.updateEmailCampaign(campaignId, updateRequest);
78+
System.out.println(updated);
79+
80+
// Aggregated performance statistics (all zeros until the campaign has been started).
81+
final var stats = campaigns.getEmailCampaignStats(campaignId);
82+
System.out.println(stats);
83+
84+
// Delete returns the deleted campaign object.
85+
final var deleted = campaigns.deleteEmailCampaign(campaignId);
86+
System.out.println(deleted);
87+
}
88+
}
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
package io.mailtrap.api.emailcampaigns;
2+
3+
import io.mailtrap.model.request.emailcampaigns.CreateEmailCampaignRequest;
4+
import io.mailtrap.model.request.emailcampaigns.UpdateEmailCampaignRequest;
5+
import io.mailtrap.model.response.emailcampaigns.EmailCampaign;
6+
import io.mailtrap.model.response.emailcampaigns.EmailCampaignListResponse;
7+
import io.mailtrap.model.response.emailcampaigns.EmailCampaignStats;
8+
9+
/**
10+
* Email Campaigns API. Manage email marketing campaigns and retrieve their performance
11+
* statistics.
12+
*
13+
* <p>The account is resolved from the API token, so these endpoints are token-scoped and the
14+
* path is not account-scoped.
15+
*/
16+
public interface EmailCampaigns {
17+
18+
/**
19+
* List the account's email campaigns, newest first.
20+
*
21+
* @param perPage number of campaigns per page (max 100, default 50); {@code null} to omit
22+
* @param search filter campaigns by name (case-insensitive partial match);
23+
* {@code null} to omit
24+
* @param token page number to retrieve (page-token pagination, default 1);
25+
* {@code null} to omit
26+
* @return a page of campaigns and the pagination metadata
27+
*/
28+
EmailCampaignListResponse getEmailCampaigns(Integer perPage, String search, Integer token);
29+
30+
/**
31+
* Create a new email campaign in the {@code draft} state.
32+
*
33+
* @param request the campaign attributes ({@code name} and {@code mailsendDomainId}
34+
* are required)
35+
* @return the created email campaign
36+
*/
37+
EmailCampaign createEmailCampaign(CreateEmailCampaignRequest request);
38+
39+
/**
40+
* Get a single email campaign by ID.
41+
*
42+
* @param emailCampaignId unique email campaign ID
43+
* @return the email campaign
44+
*/
45+
EmailCampaign getEmailCampaign(long emailCampaignId);
46+
47+
/**
48+
* Update an existing email campaign. The campaign must not be in a sending state. Only the
49+
* provided attributes are changed.
50+
*
51+
* @param emailCampaignId unique email campaign ID
52+
* @param request the attributes to update
53+
* @return the updated email campaign
54+
*/
55+
EmailCampaign updateEmailCampaign(long emailCampaignId, UpdateEmailCampaignRequest request);
56+
57+
/**
58+
* Delete an email campaign. The campaign must not be in a sending state. The deleted
59+
* campaign object is returned (HTTP 200 with body, not 204).
60+
*
61+
* @param emailCampaignId unique email campaign ID
62+
* @return the deleted email campaign
63+
*/
64+
EmailCampaign deleteEmailCampaign(long emailCampaignId);
65+
66+
/**
67+
* Get aggregated performance statistics for an email campaign. If the campaign has never
68+
* been started, all counts and rates are returned as {@code 0}.
69+
*
70+
* @param emailCampaignId unique email campaign ID
71+
* @return aggregated campaign statistics
72+
*/
73+
EmailCampaignStats getEmailCampaignStats(long emailCampaignId);
74+
75+
}
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
package io.mailtrap.api.emailcampaigns;
2+
3+
import io.mailtrap.Constants;
4+
import io.mailtrap.api.apiresource.ApiResource;
5+
import io.mailtrap.config.MailtrapConfig;
6+
import io.mailtrap.http.RequestData;
7+
import io.mailtrap.model.request.emailcampaigns.CreateEmailCampaignRequest;
8+
import io.mailtrap.model.request.emailcampaigns.UpdateEmailCampaignRequest;
9+
import io.mailtrap.model.response.emailcampaigns.EmailCampaign;
10+
import io.mailtrap.model.response.emailcampaigns.EmailCampaignListResponse;
11+
import io.mailtrap.model.response.emailcampaigns.EmailCampaignStats;
12+
13+
import java.util.Optional;
14+
15+
import static io.mailtrap.http.RequestData.entry;
16+
17+
public class EmailCampaignsImpl extends ApiResource implements EmailCampaigns {
18+
19+
private static final String BASE_PATH = "/api/email_campaigns";
20+
21+
public EmailCampaignsImpl(final MailtrapConfig config) {
22+
super(config);
23+
this.apiHost = Constants.GENERAL_HOST;
24+
}
25+
26+
@Override
27+
public EmailCampaignListResponse getEmailCampaigns(final Integer perPage, final String search, final Integer token) {
28+
final var queryParams = RequestData.buildQueryParams(
29+
entry("per_page", Optional.ofNullable(perPage)),
30+
entry("search", Optional.ofNullable(search)),
31+
entry("token", Optional.ofNullable(token))
32+
);
33+
34+
return httpClient.get(
35+
apiHost + BASE_PATH,
36+
new RequestData(queryParams),
37+
EmailCampaignListResponse.class
38+
);
39+
}
40+
41+
@Override
42+
public EmailCampaign createEmailCampaign(final CreateEmailCampaignRequest request) {
43+
return httpClient.post(
44+
apiHost + BASE_PATH,
45+
request,
46+
new RequestData(),
47+
EmailCampaign.class
48+
);
49+
}
50+
51+
@Override
52+
public EmailCampaign getEmailCampaign(final long emailCampaignId) {
53+
return httpClient.get(
54+
String.format(apiHost + BASE_PATH + "/%d", emailCampaignId),
55+
new RequestData(),
56+
EmailCampaign.class
57+
);
58+
}
59+
60+
@Override
61+
public EmailCampaign updateEmailCampaign(final long emailCampaignId, final UpdateEmailCampaignRequest request) {
62+
return httpClient.patch(
63+
String.format(apiHost + BASE_PATH + "/%d", emailCampaignId),
64+
request,
65+
new RequestData(),
66+
EmailCampaign.class
67+
);
68+
}
69+
70+
@Override
71+
public EmailCampaign deleteEmailCampaign(final long emailCampaignId) {
72+
return httpClient.delete(
73+
String.format(apiHost + BASE_PATH + "/%d", emailCampaignId),
74+
new RequestData(),
75+
EmailCampaign.class
76+
);
77+
}
78+
79+
@Override
80+
public EmailCampaignStats getEmailCampaignStats(final long emailCampaignId) {
81+
return httpClient.get(
82+
String.format(apiHost + BASE_PATH + "/%d/stats", emailCampaignId),
83+
new RequestData(),
84+
EmailCampaignStats.class
85+
);
86+
}
87+
}

‎src/main/java/io/mailtrap/client/MailtrapClient.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,12 @@ public class MailtrapClient {
6262
@Getter
6363
private final MailtrapOrganizationsApi organizationsApi;
6464

65+
/**
66+
* API for Mailtrap.io Email Campaigns functionality
67+
*/
68+
@Getter
69+
private final MailtrapEmailCampaignsApi emailCampaignsApi;
70+
6571
/**
6672
* Utility class which holds sending context (which API to use: Email Sending API, Bulk Sending API or
6773
* Email Testing API, inbox id for Email Testing API) to make it possible to perform send directly from MailtrapClient
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
package io.mailtrap.client.api;
2+
3+
import io.mailtrap.api.emailcampaigns.EmailCampaigns;
4+
import lombok.Getter;
5+
import lombok.RequiredArgsConstructor;
6+
import lombok.experimental.Accessors;
7+
8+
/**
9+
* Represents an API for Mailtrap Email Campaigns functionality.
10+
*
11+
* <p>Email campaigns use a token-scoped, non-account-scoped URL family
12+
* ({@code /api/email_campaigns}), so they are grouped under their own API rather than the
13+
* account-scoped general API.
14+
*/
15+
@Getter
16+
@Accessors(fluent = true)
17+
@RequiredArgsConstructor
18+
public class MailtrapEmailCampaignsApi {
19+
private final EmailCampaigns emailCampaigns;
20+
}

‎src/main/java/io/mailtrap/factory/MailtrapClientFactory.java‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
import io.mailtrap.api.contactimports.ContactImportsImpl;
1414
import io.mailtrap.api.contactlists.ContactListsImpl;
1515
import io.mailtrap.api.contacts.ContactsImpl;
16+
import io.mailtrap.api.emailcampaigns.EmailCampaignsImpl;
1617
import io.mailtrap.api.emailtemplates.EmailTemplatesImpl;
1718
import io.mailtrap.api.inboxes.InboxesImpl;
1819
import io.mailtrap.api.messages.MessagesImpl;
@@ -73,11 +74,18 @@ public static MailtrapClient createMailtrapClient(final MailtrapConfig config) {
7374
final var contactsApi = createContactsApi(config);
7475
final var emailTemplatesApi = createEmailTemplatesApi(config);
7576
final var organizationsApi = createOrganizationsApi(config);
77+
final var emailCampaignsApi = createEmailCampaignsApi(config);
7678

7779
final var sendingContextHolder = configureSendingContext(config);
7880

7981
return new MailtrapClient(sendingApi, testingApi, bulkSendingApi, generalApi, contactsApi, emailTemplatesApi,
80-
organizationsApi, sendingContextHolder);
82+
organizationsApi, emailCampaignsApi, sendingContextHolder);
83+
}
84+
85+
private static MailtrapEmailCampaignsApi createEmailCampaignsApi(final MailtrapConfig config) {
86+
final var emailCampaigns = new EmailCampaignsImpl(config);
87+
88+
return new MailtrapEmailCampaignsApi(emailCampaigns);
8189
}
8290

8391
private static MailtrapOrganizationsApi createOrganizationsApi(final MailtrapConfig config) {
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
package io.mailtrap.model;
2+
3+
import com.fasterxml.jackson.annotation.JsonCreator;
4+
import com.fasterxml.jackson.annotation.JsonValue;
5+
6+
/**
7+
* Current state of an email campaign in its lifecycle.
8+
*/
9+
public enum CampaignState {
10+
DRAFT("draft"),
11+
SCHEDULED("scheduled"),
12+
SENDING("sending"),
13+
SENT("sent"),
14+
TERMINATED("terminated");
15+
16+
private final String value;
17+
18+
CampaignState(String value) {
19+
this.value = value;
20+
}
21+
22+
@JsonValue
23+
public String getValue() {
24+
return value;
25+
}
26+
27+
@Override
28+
public String toString() {
29+
return value;
30+
}
31+
32+
@JsonCreator
33+
public static CampaignState fromValue(String value) {
34+
for (CampaignState state : CampaignState.values()) {
35+
if (state.value.equalsIgnoreCase(value)) {
36+
return state;
37+
}
38+
}
39+
throw new IllegalArgumentException("Unknown value: " + value);
40+
}
41+
}

0 commit comments

Comments
 (0)