Subversion Repositories SmartDukaan

package com.spice.profitmandi.common.mail;

/**
 * The single way to send mail in this system.
 *
 * Nothing sends inline. A caller hands over a {@link MailRequest} and returns;
 * delivery, retry and de-duplication happen afterwards, driven by the outbox.
 * That matters because SMTP fails often and for boring reasons — an expired
 * credential, a timeout on a large attachment, a provider refusing an
 * unauthorised sender — and an inline send loses the message when it does. It is
 * also why a report job should not be marked FAILED merely because the mail it
 * generated could not be handed over at that instant.
 *
 * The interface lives in profitmandi-common while the implementation lives in
 * profitmandi-dao, because dao depends on common and not the other way round.
 * Utils and EmailService are in common and could not otherwise reach the outbox
 * at all.
 */
public interface MailQueue {

    /**
     * Accepts a mail for delivery. Returns once the request is durably recorded,
     * not once it is sent. Implementations must not throw for delivery problems —
     * a caller has no useful response to "SMTP is down".
     */
    void queue(MailRequest request);
}