com.mailgun.api.v3.suppression.MailgunSuppressionBouncesApi Maven / Gradle / Ivy
Show all versions of mailgun-java Show documentation
package com.mailgun.api.v3.suppression;
import com.mailgun.api.MailgunApi;
import com.mailgun.model.ResponseWithMessage;
import com.mailgun.model.suppression.SuppressionResponse;
import com.mailgun.model.suppression.bounces.BouncesItem;
import com.mailgun.model.suppression.bounces.BouncesListImportRequest;
import com.mailgun.model.suppression.bounces.BouncesRequest;
import com.mailgun.model.suppression.bounces.BouncesResponse;
import feign.Headers;
import feign.Param;
import feign.RequestLine;
import feign.Response;
import java.util.List;
/**
*
* Mailgun Suppression Bounces Api
*
*
*
* Mailgun keeps three lists of addresses it blocks the delivery to: bounces, unsubscribes and complaints.
* These lists are populated automatically as Mailgun detects undeliverable addresses you try to send to
* and as recipients unsubscribe from your mailings or mark your emails as a spam (for ESPs that provide FBL).
* You can also add/remove addresses from any of these lists using the API.
*
*
* It’s important to note that these suppression lists are unique to a sending domain and are not an account level (global) suppression list.
* If you want to add/remove the same address(es) from multiple domains, you’ll need to do so for each domain.
*
*
*
* Bounce list stores events of delivery failures due to permanent recipient mailbox errors such as non-existent mailbox.
* Soft bounces (for example, mailbox is full) and other failures (for example, ESP rejects an email because it thinks it is spam) are not added to the list.
*
*
*
* Subsequent delivery attempts to an address found in a bounce list are prevented to protect your sending reputation.
*
*
*
* Mailgun can notify your application every time a message bounces via a
* ermanent_fail webhook.
*
*
* @see Suppressions/Bounces
*/
@Headers("Accept: application/json")
public interface MailgunSuppressionBouncesApi extends MailgunApi {
/**
*
* Returns a list of bounces for a domain (limit to 100 entries).
*
*
* @param domain Name of the domain
* @return {@link BouncesResponse}
*/
@RequestLine("GET /{domain}/bounces")
BouncesResponse getBounces(@Param("domain") String domain);
/**
*
* Returns a list of bounces for a domain (limit to 100 entries).
*
*
* @param domain Name of the domain
* @return {@link Response}
*/
@RequestLine("GET /{domain}/bounces")
Response getBouncesFeignResponse(@Param("domain") String domain);
/**
*
* Returns a list of bounces for a domain.
*
*
* @param domain Name of the domain
* @param limit Number of entries to return, max: 10000.
* @return {@link BouncesResponse}
*/
@RequestLine("GET /{domain}/bounces?limit={limit}")
BouncesResponse getBounces(@Param("domain") String domain, @Param("limit") Integer limit);
/**
*
* Returns a list of bounces for a domain.
*
*
* @param domain Name of the domain
* @param limit Number of entries to return, max: 10000.
* @return {@link Response}
*/
@RequestLine("GET /{domain}/bounces?limit={limit}")
Response getBouncesFeignResponse(@Param("domain") String domain, @Param("limit") Integer limit);
/**
*
* Fetch a single bounce event by a given email address.
*
*
* Useful to check if a given email address has bounced before.
*
*
* @param domain Name of the domain
* @param address An email address
* @return {@link BouncesItem}
*/
@RequestLine("GET /{domain}/bounces/{address}")
BouncesItem getBounce(@Param("domain") String domain, @Param("address") String address);
/**
*
* Fetch a single bounce event by a given email address.
*
*
* Useful to check if a given email address has bounced before.
*
*
* @param domain Name of the domain
* @param address An email address
* @return {@link Response}
*/
@RequestLine("GET /{domain}/bounces/{address}")
Response getBounceFeignResponse(@Param("domain") String domain, @Param("address") String address);
/**
*
* Add a single bounce record to the bounce list.
*
*
* Updates the existing record if the address is already there.
*
*
* @param domain Name of the domain
* @param request {@link BouncesRequest}
* @return {@link SuppressionResponse}
*/
@Headers("Content-Type: multipart/form-data")
@RequestLine("POST /{domain}/bounces")
SuppressionResponse addBounce(@Param("domain") String domain, BouncesRequest request);
/**
*
* Add a single bounce record to the bounce list.
*
*
* Updates the existing record if the address is already there.
*
*
* @param domain Name of the domain
* @param request {@link BouncesRequest}
* @return {@link Response}
*/
@Headers("Content-Type: multipart/form-data")
@RequestLine("POST /{domain}/bounces")
Response addSBounceFeignResponse(@Param("domain") String domain, BouncesRequest request);
/**
*
* Add multiple bounce records to the bounce list in a single API call.
*
*
* @param domain Name of the domain
* @param request list of {@link BouncesRequest}
* @return {@link ResponseWithMessage}
*/
@Headers("Content-Type: application/json")
@RequestLine("POST /{domain}/bounces")
ResponseWithMessage addBounces(@Param("domain") String domain, List request);
/**
*
* Add multiple bounce records to the bounce list in a single API call.
*
*
* @param domain Name of the domain
* @param request list of {@link BouncesRequest}
* @return {@link Response}
*/
@Headers("Content-Type: application/json")
@RequestLine("POST /{domain}/bounces")
Response addSBounceFeignResponses(@Param("domain") String domain, List request);
/**
*
* Import a list of bounces.
*
*
* CSV file must be 25MB or under and must contain the following column headers:
*
*
* address Valid email address
* code Error code (optional, default: 550)
* error Error description (optional, default: empty string)
* created_at Timestamp of a bounce event in RFC2822 format (optional, default: current time)
*
*
* @param domain Name of the domain
* @param request {@link BouncesListImportRequest}
* @return {@link ResponseWithMessage}
*/
@Headers("Content-Type: multipart/form-data")
@RequestLine("POST /{domain}/bounces/import")
ResponseWithMessage importBounceList(@Param("domain") String domain, BouncesListImportRequest request);
/**
*
* Import a list of bounces.
*
*
* CSV file must be 25MB or under and must contain the following column headers:
*
*
* address Valid email address
* code Error code (optional, default: 550)
* error Error description (optional, default: empty string)
* created_at Timestamp of a bounce event in RFC2822 format (optional, default: current time)
*
*
* @param domain Name of the domain
* @param request {@link BouncesListImportRequest}
* @return {@link Response}
*/
@Headers("Content-Type: multipart/form-data")
@RequestLine("POST /{domain}/bounces/import")
Response importBounceListFeignResponses(@Param("domain") String domain, BouncesListImportRequest request);
/**
*
* Delete a single bounce.
* Clears a given bounce event.
*
*
* The delivery to the deleted email address resumes until it bounces again.
*
*
* @param domain Name of the domain
* @param address An email address
* @return {@link ResponseWithMessage}
*/
@RequestLine("DELETE /{domain}/bounces/{address}")
ResponseWithMessage deleteBounce(@Param("domain") String domain, @Param("address") String address);
/**
*
* Delete a single bounce.
* Clears a given bounce event.
*
*
* The delivery to the deleted email address resumes until it bounces again.
*
*
* @param domain Name of the domain
* @param address An email address
* @return {@link Response}
*/
@RequestLine("DELETE /{domain}/bounces/{address}")
Response deleteBounceFeignResponse(@Param("domain") String domain, @Param("address") String address);
/**
*
* Delete all bounced email addresses for a domain.
* Delivery to the deleted email addresses will no longer be suppressed.
*
*
* @param domain Name of the domain
* @return {@link ResponseWithMessage}
*/
@RequestLine("DELETE /{domain}/bounces")
ResponseWithMessage deleteAllBounces(@Param("domain") String domain);
/**
*
* Delete all bounced email addresses for a domain.
* Delivery to the deleted email addresses will no longer be suppressed.
*
*
* @param domain Name of the domain
* @return {@link Response}
*/
@RequestLine("DELETE /{domain}/bounces")
Response deleteAllBouncesFeignResponse(@Param("domain") String domain);
}