Invoice mails

API version 1.6.0

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

Index

Introduction
Retrieving multiple invoice mails
1. Request
2. Response
Retrieving an invoice mail
1. Request
2. Response
Creating an invoice mail
1. Request
2. Response

Introduction

The invoice mail model and its relations to other models

After creating an invoice, the client has a responsibilty to deliver the invoice to the customer. One way to do that is by printing the invoice and sending it by regular mail. The Profifact service supports that scheme by providing a method for retrieving the PDF representation of an invoice (see Retrieving an invoice).
A faster and more modern way to deliver an invoice to a customer is sending it by electronic mail. This scheme is supported through the /invoicemails resource. Besides the gains in simplicity and delivery time, a major advantage of letting Profifact send invoices 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 an invoice was sent. It may also be useful as an overview of the efforts made by the client to pursuade the customer into settling the invoice in case the debt is transferred to a collection agency or process server.

Retrieving multiple invoice mails

Clients can retrieve multiple invoice mails by sending an HTTP GET request to /invoicemails. Authentication is required and only invoice 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 invoice mails, multiple requests are needed to retrieve all items.
Unlike an HTTP GET request for a particular invoice mail (see retrieving an invoice mail), when retrieving multiple invoice 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 /invoicemails 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.
invoiceId: The integer unique ID of an invoice belonging to the client. If specified only invoice mails for the invoice with that ID are returned.

Examples


            // Retrieve invoice mails 7 through 16:

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

            

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

            GET /invoicemails?invoiceId=1003478 HTTP/1.1

            

            // Sort invoice mails by date and time:

            GET /invoicemails?order=datetime HTTP/1.1

            

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

            GET /invoicemails?order=-datetime&invoiceId=1037788 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 invoice mail objects selected for being returned based on the request.
id	int	The unique ID of the invoice mail assigned by Profifact.
invoiceId	int	The unique ID of the invoice the invoice 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 an invoice mail

Clients can retrieve a single invoice mail by sending an HTTP GET request to /invoicemails/RESOURCE_ID where RESOURCE_ID is a unique identifier of the requested invoice mail. When a single invoice 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 /invoicemails/RESOURCE_ID.

Examples


            // Retrieve a particular invoice mail:

            GET /invoicemails/10387438 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 an invoice 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 invoice mail assigned by Profifact.
invoiceId	int	The unique ID of the invoice the invoice 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 an invoice mail

A new invoice mail can be created by sending an HTTP POST request to /invoicemails. Creating an invoice mail equals sending a mail message with an attached invoice and recording that operation. The email being sent is a side effect of the process that creates a new invoice 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 invoices 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 /invoicemails 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 invoice 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
invoiceId	int		The unique ID of the invoice 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 invoice 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 invoice mail settings is used.

Examples


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

            // client's default subject and message body:

            POST /invoicemails HTTP/1.1

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

            

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

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

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

            POST /invoicemails HTTP/1.1

            {

              "invoiceId": 1087338,

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

              "copyToSelf": 1,

              "subject": "Invoice {invoice.number} - December 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 an invoice 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 invoice 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.