Send Email
The transactional Email operation consists of sending an email to one or more recipients who do not belong to the organization’s audience. As such, it does not depend on a schema previously defined for the audience of contacts.
This operation allows for the configuration of webhooks. Webhooks are endpoints configured by the client in each transactional email request, which are triggered by Arpoone to forward event information related to the activity of the sent email.
The endpoint has the following limitations:
- Maximum of 10 Emails per HTTP request to the Arpoone API, contained in the
messagesfield; - The total size of each email, including attachments, cannot exceed 10MB (megabytes). If this value is exceeded, the error
PAYLOAD_EXCEEDS_MAX_SIZEwill be returned; - The total size of the HTTP request cannot exceed 30MB (megabytes).
Sender Domains
Sender domains are the domains of the sender used in the emails sent (e.g., @arpoone.com). Sending transactional emails requires prior configuration of the domain used in the email sender.
This configuration consists of the following steps:
- Create the sender domain in the Arpoone platform:
- Accessed via: Profile Picture → Settings → Senders → Email Domains;
- Configure DKIM, SPF, and Ownership Token values in the DNS of the desired domain – contact the support team for more information.
Payload
Example of an email payload, with CC/BCC recipients, webhooks and attachments:
{
"organizationId": <uuidv4> (Guid),
"messages": [
{
"to": [ ]<string[]> (array of strings),
"cc": [ ]<string[]> (array of strings),
"bcc": [ ]<string[]> (array of strings),
"from": <string>,
"displayName": <string>,
"subject": <string>,
"textContent": <string>,
"htmlContent": <string>,
"expirationDateTime": <datetime>,
"emailWebhooks": {
"bounced": {
"url": <string>,
"enabled": <bool>
},
"clicked": {
"url": <string>,
"enabled": <bool>
},
"opened": {
"url": <string>,
"enabled": <bool>
},
"spam": {
"url": <string>,
"enabled": <bool>
},
"unsubscribed": {
"url": <string>,
"enabled": <bool>
}
},
"attachments": [
{
"mimeType": <string>,
"name": <string>,
"base64Content": <string> (base64)
}
]
},
...
]
}
Configuration
The messages property in the payload is an array, which means you can send multiple emails in a single HTTP request.
Description of the fields:
to– the primary recipients of the Email messagecc– the carbon-copy recipients of the Email messagebcc– the blind carbon-copy recipients of the Email messagefrom– sender of the email – this property must contain a valid email, and the domain must be configured previously:- For example: if a domain sender
@arpoone.comis configured, then thefromproperty will be "[address]@arpoone.com"; - If the domain sender is not configured and confirmed, the error code
FROM_NOT_ALLOWEDwill be returned;
- For example: if a domain sender
displayName– name of the email sender;textContent– plain-text content of the email;htmlContent– HTML content of the email;expirationDateTime– expiration date and time in UTC timezone when the email is sent. If there is any delay in sending emails by the platform, and the current date exceeds the configured value in this field, the email will not be sent;emailWebhooks– destination URLs for email event notifications (see Email Webhooks page). Specifying these URLs is optional;attachments– files to be sent with the email as attachments.
Please keep in mind that there is a cumulative limit of 50 recipients (the sum of To, CC and BCC) per each individual Email.
Attachments
The email attachment feature requires prior activation by the commercial team.
Transactional email sending supports attaching files, encoded in base64. To do this, include the attachments property (array). Each item in the attachments array must contain three properties: mimeType, name, and Base64Content.
The following restrictions apply:
- The
mimeTypeandnameproperties must not exceed 128 characters; - The
mimeTypeproperty must correspond to the attachment that is base64 encoded – at the same time, thenameproperty must include the correct file extension (e.g.,.jpgin the example below).
Example of attachment configuration:
...
"attachments":
[
{
"mimeType": "image/jpeg",
"name": "img.jpg",
"base64Content": "/9j/4AAQSkZJRgABAQEAYABgAA..."
}
]
...
Response
Similarly to the request body of the transactional Email endpoint, the response also contains an array messages. Inside each item in messages there will be a status property, alongside three arrays of objects containing the identifiers to each recipient configured in the To / Cc / Bcc fields of the request.
The transactional Email endpoint returns HTTP Status Code 200 (HTTP OK) if no error prevents the processing of the request. The success/error indication for each message is made in the response body, within each item in the messages array, under the status property.
The status property reflects whether the email was sent successfully or not, the cost property is the amount deducted from the organization’s balance, and the error property provides details if any error happens.
Example:
{
"error": null,
"messages": [
{
"status": "SUCCESS",
"to": [
{
"email": "example@sendit.pt",
"messageId": "6ab84ad8-ef9d-45fa-bc4f-fa54edb135b7"
}
],
"cc": [
{
"email": "example+cc@sendit.pt",
"messageId": "76326eca-600f-4b77-8288-f11fb9491628"
}
],
"bcc": [
{
"email": "example+bcc@sendit.pt",
"messageId": "b6a83257-40a0-486f-b369-ff73297b1ec9"
}
],
"cost": {
"amount": 3
},
"error": null
}
]
}
Errors
In case of errors, the error property within each item of the messages array (in the response) will be populated with an object containing information about the error that occurred:
"error":
{
"code": "PARAM_EXCEEDS_MAX_LENGTH",
"param": "DisplayName",
"description": ""
}
The code property specifies the type of error that occurred, while the param property specifies which parameter in the email send payload caused the error.
The complete list of error codes can be found here.