Profifact logo

Offer mails

API version 1.6.0

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

Index

  1. Introduction
  2. Retrieving multiple offer mails
    1. Request
    2. Response
  3. Retrieving an offer mail
    1. Request
    2. Response
  4. Creating an offer mail
    1. Request
    2. Response

Introduction

The offer mail model and its relations to other models
The offer mail model and its relations to other models

After creating an offer, the client normally delivers the offer to the customer. One way to do that is by printing the offer and sending it by regular mail. The Profifact service supports that scheme by providing a method for retrieving the PDF representation of an offer (see Retrieving an offer).
A faster and more modern way to deliver an offer to a customer is sending it by electronic mail. This scheme is supported through the /offermails resource. Besides the gains in simplicity and delivery time, a major advantage of letting Profifact send offers 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 offer was sent.

Retrieving multiple offer mails

Clients can retrieve multiple offer mails by sending an HTTP GET request to /offermails. Authentication is required and only offer 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 offer mails, multiple requests are needed to retrieve all items.
Unlike an HTTP GET request for a particular offer mail (see retrieving an offer mail), when retrieving multiple offer 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 /offermails 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.
offerId
The integer unique ID of an offer belonging to the client. If specified only offer mails for the offer with that ID are returned.
Examples
// Retrieve offer mails 7 through 16:
GET /offermails?offset=7&limit=10 HTTP/1.1

// Retrieve upto 100 offer mails for a particular offer:
GET /offermails?offerId=1003478 HTTP/1.1

// Sort offer mails by date and time:
GET /offermails?order=datetime HTTP/1.1

// Get offer mails for a particular offer sorted by date and time in descending order
GET /offermails?order=-datetime&offerId=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 offer mail objects selected for being returned based on the request.
id int The unique ID of the offer mail assigned by Profifact.
offerId int The unique ID of the offer the offer 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 offer mail

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

Examples
// Retrieve a particular offer mail:
GET /offermails/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 offer 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 offer mail assigned by Profifact.
offerId int The unique ID of the offer the offer 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 offer mail

A new offer mail can be created by sending an HTTP POST request to /offermails. Creating an offer mail equals sending a mail message with an attached offer and recording that operation. The email being sent is a side effect of the process that creates a new offer 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 offers 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 /offermails 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 offer 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
offerId int The unique ID of the offer 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 offer 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 offer mail settings is used.
Examples
// Send a mail message with a PDF offer to a single customer using the
// client's default subject and message body:
POST /offermails HTTP/1.1
{ "offerId": 1087349, "recipients": [ "info@example.org" ] }

// Send a mail message with a PDF offer to multiple recipients with a custom
// subject and a custom message ({offer.number} is replaced by the actual
// offer number). Also, send a copy of the message to the client:
POST /offermails HTTP/1.1
{
  "offerId": 1087338,
  "recipients": [ "info@example.org", "name@mycustomer.tld" ],
  "copyToSelf": 1,
  "subject": "Offer {offer.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 offer 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 offer 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.