Reminder mails

API version 1.6.0

Once a reminder is created, in most cases, it must be sent to the customer. This article describes how to send emails with attached reminders using the Profifact service and how to retrieve previously sent emails.

Index

Introduction
Retrieving multiple reminder mails
1. Request
2. Response
Retrieving a reminder mail
1. Request
2. Response
Creating a reminder mail
1. Request
2. Response

Introduction

The reminder mail model and its relations to other models

After creating a reminder, the client usually decides to deliver the reminder to the customer. One way to do that is by printing the reminder and sending it by regular mail. The Profifact service supports that scheme by providing a method for retrieving the PDF representation of a reminder (see Retrieving a reminder).
A faster and more modern way to deliver a reminder to a customer is sending it by electronic mail. This scheme is supported through the /remindermails resource. Besides the gains in simplicity and delivery time, a major advantage of letting Profifact send reminders by email is the fact that Profifact keeps track of all mail messages it sends for the client. The log of sent messages can be used for later reference to identify when a reminder was sent. It may also be useful as an overview of the efforts made by the client to pursuade the customer into settling the associated invoices in case a debt is transferred to a collection agency or process server.

Retrieving multiple reminder mails

Clients can retrieve multiple reminder mails by sending an HTTP GET request to /remindermails. Authentication is required and only reminder mails owned by the client are returned. If no limit is specified, the maximum number of items returned is 100. If a client has more than 100 reminder mails, multiple requests are needed to retrieve all items.
Unlike an HTTP GET request for a particular reminder mail (see retrieving a reminder mail), when retrieving multiple reminders mails the message property of each item is not included in the results. This signicantly reduces the amount of data that needs to be transferred from the service to the client.

Request

HTTP GET requests to /remindermails may include any of the following GET parameters:

order: A comma separated set of field names specifying the sort order of the matching items. A minus sign preceeding a field name indicates descending sort order.
offset: The offset of the first item to return from the collection of matching items.
limit: The maximum number of items to return.
reminderId: The integer unique ID of a reminder belonging to the client. If specified only reminder mails for the reminder with that ID are returned.

Examples


            // Retrieve reminder mails 7 through 16:

            GET /remindermails?offset=7&limit=10 HTTP/1.1

            

            // Retrieve upto 100 reminder mails for a particular reminder:

            GET /remindermails?reminderId=3972347 HTTP/1.1

            

            // Sort reminder mails by date and time:

            GET /remindermails?order=datetime HTTP/1.1

            

            // Get reminder mails for a particular reminder sorted by date and time in descending order

            GET /remindermails?order=-datetime&reminderId=1031238 HTTP/1.1

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains a data structure with the members defined in the table below. See the section on data types for an explanation of property data types.

Name	Type	Description
count	int	Specifies the number of items returned.
total	int	Specifies the total number of matching items.
offset	int	Specifies the offset of the first returned item in the collection of all matching items.
items	array	The array of the reminder mail objects selected for being returned based on the request.
id	int	The unique ID of the reminder mail assigned by Profifact.
reminderId	int	The unique ID of the reminder the reminder mail was sent for.
datetime	datetime	The date and time at which the email represented by the item was sent.
recipients	array	An array of on or more strings representing the recipients of the email represented by the item.
subject	string	The subject of the email represented by the item.

Retrieving a reminder mail

Clients can retrieve a single reminder mail by sending an HTTP GET request to /remindermails/RESOURCE_ID where RESOURCE_ID is a unique identifier of the requested reminder mail. When a single reminder mail object is retrieved the full message of the email represented by that object is included in the result.

Request

Currently, no additional GET parameters are supported for requests to /remindermails/RESOURCE_ID.

Examples


            // Retrieve a particular reminder mail:

            GET /remindermails/7008 HTTP/1.1

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 200 OK is returned and the response body contains a reminder mail object whose members are shown in the following table. See the section on data types for an explanation of property data types.

Name	Type	Description
id	int	The unique ID of the reminder mail assigned by Profifact.
reminderId	int	The unique ID of the reminder the reminder mail was sent for.
datetime	datetime	The date and time at which the email represented by the item was sent.
recipients	array	An array of one or more strings representing the recipients of the email represented by the item.
subject	string	The subject of the email represented by the item.
message	string	The full message of the email represented by the item.

Creating a reminder mail

A new reminder mail can be created by sending an HTTP POST request to /remindermails. Creating a reminder mail equals sending a mail message with an attached reminder and recording that operation. The email being sent is a side effect of the process that creates a new reminder mail object.
Profifact could send mail messages from the client's mail address, but those messages would surely end up in the spam folders of the recipients, because Profifact is not a known mail submission agent for the client's domain. Instead, Profifact sends mail messages from noreply@profifact.nl with the display name set to the name of the client. Recipients usually see only the display name of the sender and will therefore assume that the message was sent by the client (which it is, because the client initiated the action to send the message). To ensure that replies are sent to the client and not to Profifact, the Reply-to header of an outgoing mail message is set to the email address of the client.

Using the Profifact service for purposes other than legitimately sending a reasonable quantity of reminders to customers may lead to an immediate revocation of all access and a liablity claim for damages resulting from the illegitimate use.

Request

HTTP POST requests to /remindermails are validated before a message is sent. Valid requests must provide valid values for the mandatory fields listed in the table below. If specified, values for optional fields must be valid as well. Once the service has completed validation and accepted a request, it generates a PDF copy of the reminder with the ID specified in the request. The PDF copy is attached to a mail message and sent to the specified recipients.
Clients may provide values for the following properties. See the section on data types for an explanation of property data types.

Name	Type	Valid values	Description
reminderId	int		The unique ID of the reminder for which to send a mail message.
recipients	array		An array of one to five email addresses indicating the recipients of the mail message.
copyToSelf	bool?		Indicates whether to send a carbon copy (CC) of the message to the user. If this field is present and evaluates to true, the email address of the client is added to the CC header of the message.
subject	string?	^.{0,255}$	The subject of the mail message. If this property is missing or if its value is null, the subject from the client's reminder mail settings is used.
message	string?	^.{0,8192}$	The full text to send in the body of the mail message. HTML messages are currently not supported. If this property is missing or if its value is null, the message from the client's reminder mail settings is used.

Examples


            // Send a mail message with a PDF reminder to a single customer using the

            // client's default subject and message body:

            POST /remindermails HTTP/1.1

            { "reminderId": 1087349, "recipients": [ "info@example.org" ] }

            

            // Send a mail message with a PDF reminder to multiple recipients with a custom

            // subject and a custom message ({reminder.number} is replaced by the actual

            // reminder number). Also, send a copy of the message to the client:

            POST /remindermails HTTP/1.1

            {

              "reminderId": 1087338,

              "recipients": [ "info@example.org", "name@mycustomer.tld" ],

              "copyToSelf": 1,

              "subject": "Reminder {reminder.number} - June 2016",

              "message": "Dear customer, ... With kind regards, My Name"

            }

Response

The Profifact server may send any of the status codes defined in response status codes in response to an incoming request. For a valid request HTTP status 201 Created is returned and the response body contains exactly the same information as the Retrieving a reminder mail response. If the request is valid, but the server fails to send the message, HTTP status 500 Internal Server Error is returned. If a message is sent the server adds a new reminder mail object and returns it in the response. Due to the way the internet mail system works, a successful request does not necessarily mean that any or all recipients will receive the message. The message may be bounced, for example because the mailbox for a recipient address does not exist.