All Downloads are FREE. Search and download functionalities are using the official Maven repository.

uk.gov.service.notify.NotificationClientApi Maven / Gradle / Ivy

Go to download

Use this client to send emails, text messages and letters using the GOV.UK Notify API.

There is a newer version: 5.2.1-RELEASE
Show newest version
package uk.gov.service.notify;


import java.io.File;
import java.io.InputStream;
import java.util.Map;

public interface NotificationClientApi {

    /**
     * The sendEmail method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param templateId      The template id is visible on the template page in the application.
     * @param emailAddress    The email address
     * @param personalisation Map representing the placeholders for the template if any. For example, key=name value=Bob
     *                        Can be an empty map or null when the template does not require placeholders.
     * @param reference       A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                        This reference can be unique or used used to refer to a batch of notifications.
     *                        Can be an empty string or null, when you do not require a reference for the notifications.
     * @return SendEmailResponse
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#send-an-email-error-codes
     */
    SendEmailResponse sendEmail(String templateId, String emailAddress, Map personalisation, String reference) throws NotificationClientException;


    /**
     * The sendEmail method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param templateId      The template id is visible on the template page in the application.
     * @param emailAddress    The email address
     * @param personalisation Map representing the placeholders for the template if any. For example, key=name value=Bob
     *                        Can be an empty map or null when the template does not require placeholders.
     * @param reference       A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                        This reference can be unique or used used to refer to a batch of notifications.
     *                        Can be an empty string or null, when you do not require a reference for the notifications.
     * @param emailReplyToId  An optional identifier for a reply to email address for the notification, rather than use the service default.
     *                        Service emailReplyToIds can be accessed via the service settings / manage email reply to addresses page.
     *                        Omit this argument to use the default service email reply to address.
     * @return SendEmailResponse
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#send-an-email-error-codes
     */
    SendEmailResponse sendEmail(String templateId, String emailAddress, Map personalisation, String reference, String emailReplyToId) throws NotificationClientException;

    /**
     * The sendSms method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param templateId      The template id is visible from the template page in the application.
     * @param phoneNumber     The mobile phone number
     * @param personalisation Map representing the placeholders for the template if any. For example, key=name value=Bob
     *                        Can be an empty map or null when the template does not require placeholders.
     * @param reference       A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                        This reference can be unique or used used to refer to a batch of notifications.
     *                        Can be an empty string or null, when you do not require a reference for the notifications.
     * @return SendSmsResponse
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#error-codes
     */
    SendSmsResponse sendSms(String templateId, String phoneNumber, Map personalisation, String reference) throws NotificationClientException;

    /**
     * The sendSms method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param templateId      The template id is visible from the template page in the application.
     * @param phoneNumber     The mobile phone number
     * @param personalisation Map representing the placeholders for the template if any. For example, key=name value=Bob
     *                        Can be an empty map or null when the template does not require placeholders.
     * @param reference       A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                        This reference can be unique or used used to refer to a batch of notifications.
     *                        Can be an empty string or null, when you do not require a reference for the notifications.
     * @param smsSenderId     An optional identifier for the text message sender of the notification, rather than use the service default.
     *                        Service smsSenderIds can be accessed via the service settings / manage text message senders page.
     *                        Omit this argument to use the default service text message sender.
     * @return SendSmsResponse
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#error-codes
     */
    SendSmsResponse sendSms(String templateId, String phoneNumber, Map personalisation, String reference, String smsSenderId) throws NotificationClientException;

    /**
     * The sendLetter method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param templateId      Find templateId by clicking API info for the template you want to send
     * @param personalisation Map representing the placeholders for the template if any. For example, key=name value=Bob.
     *                        Must include the keys "address_line_1", "address_line_2" and "postcode".
     * @param reference       A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                        This reference can be unique or used used to refer to a batch of notifications.
     *                        Can be an empty string or null, when you do not require a reference for the notifications.
     * @return SendLetterResponse
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#send-a-letter-error-codes
     */
    SendLetterResponse sendLetter(String templateId, Map personalisation, String reference) throws NotificationClientException;

    /**
     * The sendPrecompiledLetter method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param reference                 A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                                  This reference can be unique or used used to refer to a batch of notifications.
     *                                  Cannot be an empty string or null for precompiled PDF files.
     * @param precompiledPDF            A file containing a PDF conforming to the Notify standards for printing.
     *                                  The file must be a PDF and cannot be null.
     * @return LetterResponse
     *
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#send-a-precompiled-letter-error-codes
     */
    LetterResponse sendPrecompiledLetter(String reference, File precompiledPDF) throws NotificationClientException;

    /**
     * The sendPrecompiledLetter method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param reference                 A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                                  This reference can be unique or used used to refer to a batch of notifications.
     *                                  Cannot be an empty string or null for precompiled PDF files.
     * @param precompiledPDF            A file containing a PDF conforming to the Notify standards for printing.
     *                                  The file must be a PDF and cannot be null.
     * @param postage                   You can choose first or second class postage for your precompiled letter.
     *                                  Set the value to first for first class, or second for second class. If you do not pass in this argument, the postage will default to second class.
     * @return LetterResponse
     *
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#send-a-precompiled-letter-error-codes
     */
    LetterResponse sendPrecompiledLetter(String reference, File precompiledPDF, String postage) throws NotificationClientException;

    /**
     * The sendPrecompiledLetterWithInputStream method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param reference                 A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                                  This reference can be unique or used used to refer to a batch of notifications.
     *                                  Cannot be an empty string or null for precompiled PDF files.
     * @param stream                    An InputStream conforming to the Notify standards for printing.
     *                                  The InputStream cannot be null.
     * @return LetterResponse
     *
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#send-a-precompiled-letter-error-codes
     */
    LetterResponse sendPrecompiledLetterWithInputStream(String reference, InputStream stream) throws NotificationClientException;

    /**
     * The sendPrecompiledLetterWithInputStream method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
     *
     * @param reference                 A reference specified by the service for the notification. Get all notifications can be filtered by this reference.
     *                                  This reference can be unique or used used to refer to a batch of notifications.
     *                                  Cannot be an empty string or null for precompiled PDF files.
     * @param stream                    An InputStream conforming to the Notify standards for printing.
     *                                  The InputStream cannot be null.
     * @param postage                   You can choose first or second class postage for your precompiled letter.
     *                                  Set the value to first for first class, or second for second class. If you do not pass in this argument, the postage will default to second class.

     * @return LetterResponse
     *
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#send-a-precompiled-letter-error-codes
     */
    LetterResponse sendPrecompiledLetterWithInputStream(String reference, InputStream stream, String postage) throws NotificationClientException;

    /**
     * The getNotificationById method will return a Notification for a given notification id.
     * The id can be retrieved from the NotificationResponse of a sendEmail, sendLetter or sendSms request.
     *
     * @param notificationId The id of the notification.
     * @return Notification
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#get-the-status-of-one-message-error-codes
     */
    Notification getNotificationById(String notificationId) throws NotificationClientException;

    /**
     * The getPdfForLetter method will return a byte[] containing the PDF contents of a given letter notification.
     * The id can be retrieved from the NotificationResponse of a sendLetter.
     *
     * @param notificationId The id of the notification.
     * @return byte[] The raw pdf data.
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#get-a-pdf-for-a-letter-notification-error-codes
     */
    byte[] getPdfForLetter(String notificationId) throws NotificationClientException;

    /**
     * The getNotifications method will create a GET HTTPS request to retrieve all the notifications.
     *
     * @param status If status is not empty or null notifications will only return notifications for the given status.
     *               Possible statuses are created|sending|delivered|permanent-failure|temporary-failure|technical-failure
     * @param notification_type If notification_type is not empty or null only notifications of the given status will be returned.
     *                          Possible notificationTypes are sms|email
     * @param reference If reference is not empty or null only the notifications with that reference are returned.
     * @param olderThanId If olderThanId is not empty or null only the notifications older than that notification id are returned.
     * @return NotificationList
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#get-the-status-of-multiple-messages-error-codes
     */
    NotificationList getNotifications(String status, String notification_type, String reference, String olderThanId) throws NotificationClientException;

    /**
     * The getTemplateById returns a Template given the template id.
     *
     * @param templateId The template id is visible on the template page in the application.
     * @return Template
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#get-a-template-by-id-error-codes
     */
    Template getTemplateById(String templateId) throws NotificationClientException;

    /**
     * The getTemplateVersion returns a Template given the template id and version.
     *
     * @param templateId The template id is visible on the template page in the application.
     * @param version The version of the template to return
     * @return Template
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#get-a-template-by-id-and-version-error-codes
     */
    Template getTemplateVersion(String templateId, int version) throws NotificationClientException;

    /**
     * Returns all the templates for your service. Filtered by template type if not null.
     *
     * @param templateType If templateType is not empty or null templates will be filtered by type.
     *          Possible template types are email|sms|letter
     * @return TemplateList
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#get-a-template-by-id-error-codes
     */
    TemplateList getAllTemplates(String templateType) throws NotificationClientException;

    /**
     * The generateTemplatePreview returns a template with the placeholders replaced with the given personalisation.
     *
     * @param templateId The template id is visible from the template page in the application.
     * @param personalisation Map representing the placeholders for the template if any. For example, key=name value=Bob
     *                        Can be an empty map or null when the template does not require placeholders.
     * @return Template
     * @throws NotificationClientException see https://docs.notifications.service.gov.uk/java.html#generate-a-preview-template-error-codes
     */
    TemplatePreview generateTemplatePreview(String templateId, Map personalisation) throws NotificationClientException;

    /**
     * The getReceivedTextMessages returns a list of ReceivedTextMessage, the list is sorted by createdAt descending.
     * @param olderThanId If olderThanId is not empty or null only the received text messages older than that id are returned.
     * @return ReceivedTextMessageList
     * @throws NotificationClientException
     */
    ReceivedTextMessageList getReceivedTextMessages(String olderThanId) throws NotificationClientException;
}




© 2015 - 2024 Weber Informatics LLC | Privacy Policy