Package uk.gov.service.notify

Class NotificationClient

    • Constructor Summary

      Constructors 
      Constructor Description
      NotificationClient​(java.lang.String apiKey)
      This client constructor given the api key.
      NotificationClient​(java.lang.String apiKey, java.lang.String baseUrl)
      This client constructor is used for testing on other environments, used by the GOV.UK Notify team.
      NotificationClient​(java.lang.String apiKey, java.lang.String baseUrl, java.net.Proxy proxy)  
      NotificationClient​(java.lang.String apiKey, java.lang.String baseUrl, java.net.Proxy proxy, javax.net.ssl.SSLContext sslContext)  
      NotificationClient​(java.lang.String apiKey, java.net.Proxy proxy)
      Use this client constructor if you require a proxy for https requests.

    • Method Summary

      Modifier and Type Method Description
      TemplatePreview generateTemplatePreview​(java.lang.String templateId, java.util.Map<java.lang.String,​java.lang.Object> personalisation)
      The generateTemplatePreview returns a template with the placeholders replaced with the given personalisation.
      TemplateList getAllTemplates​(java.lang.String templateType)
      Returns all the templates for your service.
      java.lang.String getApiKey()  
      java.lang.String getBaseUrl()  
      Notification getNotificationById​(java.lang.String notificationId)
      The getNotificationById method will return a Notification for a given notification id.
      NotificationList getNotifications​(java.lang.String status, java.lang.String notification_type, java.lang.String reference, java.lang.String olderThanId)
      The getNotifications method will create a GET HTTPS request to retrieve all the notifications.
      byte[] getPdfForLetter​(java.lang.String notificationId)
      The getPdfForLetter method will return a byte[] containing the PDF contents of a given letter notification.
      java.net.Proxy getProxy()  
      ReceivedTextMessageList getReceivedTextMessages​(java.lang.String olderThanId)
      The getReceivedTextMessages returns a list of ReceivedTextMessage, the list is sorted by createdAt descending.
      java.lang.String getServiceId()  
      Template getTemplateById​(java.lang.String templateId)
      The getTemplateById returns a Template given the template id.
      Template getTemplateVersion​(java.lang.String templateId, int version)
      The getTemplateVersion returns a Template given the template id and version.
      java.lang.String getUserAgent()  
      static org.json.JSONObject prepareUpload​(byte[] documentContents)
      Use the prepareUpload method when uploading a document via sendEmail.
      SendEmailResponse sendEmail​(java.lang.String templateId, java.lang.String emailAddress, java.util.Map<java.lang.String,​?> personalisation, java.lang.String reference)
      The sendEmail method will create an HTTPS POST request.
      SendEmailResponse sendEmail​(java.lang.String templateId, java.lang.String emailAddress, java.util.Map<java.lang.String,​?> personalisation, java.lang.String reference, java.lang.String emailReplyToId)
      The sendEmail method will create an HTTPS POST request.
      SendLetterResponse sendLetter​(java.lang.String templateId, java.util.Map<java.lang.String,​?> personalisation, java.lang.String reference)
      The sendLetter method will create an HTTPS POST request.
      LetterResponse sendPrecompiledLetter​(java.lang.String reference, java.io.File precompiledPDF)
      The sendPrecompiledLetter method will create an HTTPS POST request.
      LetterResponse sendPrecompiledLetter​(java.lang.String reference, java.io.File precompiledPDF, java.lang.String postage)
      The sendPrecompiledLetter method will create an HTTPS POST request.
      LetterResponse sendPrecompiledLetterWithInputStream​(java.lang.String reference, java.io.InputStream stream)
      The sendPrecompiledLetterWithInputStream method will create an HTTPS POST request.
      LetterResponse sendPrecompiledLetterWithInputStream​(java.lang.String reference, java.io.InputStream stream, java.lang.String postage)
      The sendPrecompiledLetterWithInputStream method will create an HTTPS POST request.
      SendSmsResponse sendSms​(java.lang.String templateId, java.lang.String phoneNumber, java.util.Map<java.lang.String,​?> personalisation, java.lang.String reference)
      The sendSms method will create an HTTPS POST request.
      SendSmsResponse sendSms​(java.lang.String templateId, java.lang.String phoneNumber, java.util.Map<java.lang.String,​?> personalisation, java.lang.String reference, java.lang.String smsSenderId)
      The sendSms method will create an HTTPS POST request.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • NotificationClient

        public NotificationClient​(java.lang.String apiKey)
        This client constructor given the api key.
        Parameters:
        apiKey - Generate an API key by signing in to GOV.UK Notify, https://www.notifications.service.gov.uk, and going to the **API integration** page

      • NotificationClient

        public NotificationClient​(java.lang.String apiKey,
                          java.net.Proxy proxy)
        Use this client constructor if you require a proxy for https requests.
        Parameters:
        apiKey - Generate an API key by signing in to GOV.UK Notify, https://www.notifications.service.gov.uk, and going to the **API integration** page
        proxy - Proxy used on the http requests

      • NotificationClient

        public NotificationClient​(java.lang.String apiKey,
                          java.lang.String baseUrl)
        This client constructor is used for testing on other environments, used by the GOV.UK Notify team.
        Parameters:
        apiKey - Generate an API key by signing in to GOV.UK Notify, https://www.notifications.service.gov.uk, and going to the **API integration** page
        baseUrl - base URL, defaults to https://api.notifications.service.gov.uk

      • NotificationClient

        public NotificationClient​(java.lang.String apiKey,
                          java.lang.String baseUrl,
                          java.net.Proxy proxy)
        Parameters:
        apiKey - Generate an API key by signing in to GOV.UK Notify, https://www.notifications.service.gov.uk, and going to the **API integration** page
        baseUrl - base URL, defaults to https://api.notifications.service.gov.uk
        proxy - Proxy used on the http requests

      • NotificationClient

        public NotificationClient​(java.lang.String apiKey,
                          java.lang.String baseUrl,
                          java.net.Proxy proxy,
                          javax.net.ssl.SSLContext sslContext)

    • Method Detail

      • getUserAgent

        public java.lang.String getUserAgent()

      • getApiKey

        public java.lang.String getApiKey()

      • getServiceId

        public java.lang.String getServiceId()

      • getBaseUrl

        public java.lang.String getBaseUrl()

      • getProxy

        public java.net.Proxy getProxy()

      • sendEmail

        public SendEmailResponse sendEmail​(java.lang.String templateId,
                                   java.lang.String emailAddress,
                                   java.util.Map<java.lang.String,​?> personalisation,
                                   java.lang.String reference)
                            throws NotificationClientException
        Description copied from 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.
        Specified by:
        sendEmail in interface NotificationClientApi
        Parameters:
        templateId - The template id is visible on the template page in the application.
        emailAddress - The email address
        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.
        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.
        Returns:
        SendEmailResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#send-an-email-error-codes

      • sendEmail

        public SendEmailResponse sendEmail​(java.lang.String templateId,
                                   java.lang.String emailAddress,
                                   java.util.Map<java.lang.String,​?> personalisation,
                                   java.lang.String reference,
                                   java.lang.String emailReplyToId)
                            throws NotificationClientException
        Description copied from 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.
        Specified by:
        sendEmail in interface NotificationClientApi
        Parameters:
        templateId - The template id is visible on the template page in the application.
        emailAddress - The email address
        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.
        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.
        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.
        Returns:
        SendEmailResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#send-an-email-error-codes

      • sendSms

        public SendSmsResponse sendSms​(java.lang.String templateId,
                               java.lang.String phoneNumber,
                               java.util.Map<java.lang.String,​?> personalisation,
                               java.lang.String reference)
                        throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The sendSms method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
        Specified by:
        sendSms in interface NotificationClientApi
        Parameters:
        templateId - The template id is visible from the template page in the application.
        phoneNumber - The mobile phone number
        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.
        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.
        Returns:
        SendSmsResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#error-codes

      • sendSms

        public SendSmsResponse sendSms​(java.lang.String templateId,
                               java.lang.String phoneNumber,
                               java.util.Map<java.lang.String,​?> personalisation,
                               java.lang.String reference,
                               java.lang.String smsSenderId)
                        throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The sendSms method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
        Specified by:
        sendSms in interface NotificationClientApi
        Parameters:
        templateId - The template id is visible from the template page in the application.
        phoneNumber - The mobile phone number
        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.
        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.
        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.
        Returns:
        SendSmsResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#error-codes

      • sendLetter

        public SendLetterResponse sendLetter​(java.lang.String templateId,
                                     java.util.Map<java.lang.String,​?> personalisation,
                                     java.lang.String reference)
                              throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The sendLetter method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
        Specified by:
        sendLetter in interface NotificationClientApi
        Parameters:
        templateId - Find templateId by clicking API info for the template you want to send
        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".
        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.
        Returns:
        SendLetterResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#send-a-letter-error-codes

      • getNotificationById

        public Notification getNotificationById​(java.lang.String notificationId)
                                 throws NotificationClientException
        Description copied from interface: NotificationClientApi
        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.
        Specified by:
        getNotificationById in interface NotificationClientApi
        Parameters:
        notificationId - The id of the notification.
        Returns:
        Notification
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#get-the-status-of-one-message-error-codes

      • getPdfForLetter

        public byte[] getPdfForLetter​(java.lang.String notificationId)
                       throws NotificationClientException
        Description copied from interface: NotificationClientApi
        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.
        Specified by:
        getPdfForLetter in interface NotificationClientApi
        Parameters:
        notificationId - The id of the notification.
        Returns:
        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

      • getNotifications

        public NotificationList getNotifications​(java.lang.String status,
                                         java.lang.String notification_type,
                                         java.lang.String reference,
                                         java.lang.String olderThanId)
                                  throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The getNotifications method will create a GET HTTPS request to retrieve all the notifications.
        Specified by:
        getNotifications in interface NotificationClientApi
        Parameters:
        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
        notification_type - If notification_type is not empty or null only notifications of the given status will be returned. Possible notificationTypes are sms|email
        reference - If reference is not empty or null only the notifications with that reference are returned.
        olderThanId - If olderThanId is not empty or null only the notifications older than that notification id are returned.
        Returns:
        NotificationList
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#get-the-status-of-multiple-messages-error-codes

      • getTemplateVersion

        public Template getTemplateVersion​(java.lang.String templateId,
                                   int version)
                            throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The getTemplateVersion returns a Template given the template id and version.
        Specified by:
        getTemplateVersion in interface NotificationClientApi
        Parameters:
        templateId - The template id is visible on the template page in the application.
        version - The version of the template to return
        Returns:
        Template
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#get-a-template-by-id-and-version-error-codes

      • getAllTemplates

        public TemplateList getAllTemplates​(java.lang.String templateType)
                             throws NotificationClientException
        Description copied from interface: NotificationClientApi
        Returns all the templates for your service. Filtered by template type if not null.
        Specified by:
        getAllTemplates in interface NotificationClientApi
        Parameters:
        templateType - If templateType is not empty or null templates will be filtered by type. Possible template types are email|sms|letter
        Returns:
        TemplateList
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#get-a-template-by-id-error-codes

      • generateTemplatePreview

        public TemplatePreview generateTemplatePreview​(java.lang.String templateId,
                                               java.util.Map<java.lang.String,​java.lang.Object> personalisation)
                                        throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The generateTemplatePreview returns a template with the placeholders replaced with the given personalisation.
        Specified by:
        generateTemplatePreview in interface NotificationClientApi
        Parameters:
        templateId - The template id is visible from the template page in the application.
        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.
        Returns:
        Template
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#generate-a-preview-template-error-codes

      • prepareUpload

        public static org.json.JSONObject prepareUpload​(byte[] documentContents)
                                         throws NotificationClientException
        Use the prepareUpload method when uploading a document via sendEmail. The prepareUpload method creates a JSONObject which will need to be added to the personalisation map.
        Parameters:
        documentContents - byte[] of the document
        Returns:
        JSONObject a json object to be added to the personalisation is returned
        Throws:
        NotificationClientException

      • sendPrecompiledLetter

        public LetterResponse sendPrecompiledLetter​(java.lang.String reference,
                                            java.io.File precompiledPDF)
                                     throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The sendPrecompiledLetter method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
        Specified by:
        sendPrecompiledLetter in interface NotificationClientApi
        Parameters:
        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.
        precompiledPDF - A file containing a PDF conforming to the Notify standards for printing. The file must be a PDF and cannot be null.
        Returns:
        LetterResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#send-a-precompiled-letter-error-codes

      • sendPrecompiledLetter

        public LetterResponse sendPrecompiledLetter​(java.lang.String reference,
                                            java.io.File precompiledPDF,
                                            java.lang.String postage)
                                     throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The sendPrecompiledLetter method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
        Specified by:
        sendPrecompiledLetter in interface NotificationClientApi
        Parameters:
        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.
        precompiledPDF - A file containing a PDF conforming to the Notify standards for printing. The file must be a PDF and cannot be null.
        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.
        Returns:
        LetterResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#send-a-precompiled-letter-error-codes

      • sendPrecompiledLetterWithInputStream

        public LetterResponse sendPrecompiledLetterWithInputStream​(java.lang.String reference,
                                                           java.io.InputStream stream)
                                                    throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The sendPrecompiledLetterWithInputStream method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
        Specified by:
        sendPrecompiledLetterWithInputStream in interface NotificationClientApi
        Parameters:
        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.
        stream - An InputStream conforming to the Notify standards for printing. The InputStream cannot be null.
        Returns:
        LetterResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#send-a-precompiled-letter-error-codes

      • sendPrecompiledLetterWithInputStream

        public LetterResponse sendPrecompiledLetterWithInputStream​(java.lang.String reference,
                                                           java.io.InputStream stream,
                                                           java.lang.String postage)
                                                    throws NotificationClientException
        Description copied from interface: NotificationClientApi
        The sendPrecompiledLetterWithInputStream method will create an HTTPS POST request. A JWT token will be created and added as an Authorization header to the request.
        Specified by:
        sendPrecompiledLetterWithInputStream in interface NotificationClientApi
        Parameters:
        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.
        stream - An InputStream conforming to the Notify standards for printing. The InputStream cannot be null.
        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.
        Returns:
        LetterResponse
        Throws:
        NotificationClientException - see https://docs.notifications.service.gov.uk/java.html#send-a-precompiled-letter-error-codes