Offer mails
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
Introduction
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 |
| 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
|
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"
}