This page provides you with information about how to use MailUp REST API to create email messages and to send them to specified recipients.
| Panel | ||
|---|---|---|
| ||
...
On this page:
| Table of Contents |
|---|
...
Email messages
An email message is always created inside the environment of a MailUp list, so it cannot be managed outside of that list.
...
| Note | ||
|---|---|---|
| ||
|
Description | Create a new email message | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | |||||||||||||||||||||
URL |
| |||||||||||||||||||||
JSON request (example) |
| |||||||||||||||||||||
JSON response (example) |
|
Paging and filtering (example) |
|---|
Enable Dynamic fields
Description | Enable or disable dynamic fields | |||||
|---|---|---|---|---|---|---|
HTTP Method | PUT | |||||
URL |
| |||||
JSON request (example) |
|
JSON response (example) | Message details are returned |
|---|
Paging and filtering (example) |
|---|
List Messages
| Description | Retrieve email messages of a specified list | ||
|---|---|---|---|
HTTP Method | GET | ||
URL | Retrieve all email messages of that list
|
Retrieve only email messages that have been published (i.e. with public visibility, see details) 1
|
Retrieve only email messages that have been archived (see details) 1
|
Note: 1 an empty list is returned if public visibility of messages (aka Web library) is disabled. You shall enable it to Retrieve them | ||||||||||||||||
JSON request (example) | none | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
JSON response (example) | All email messages of a specified list
|
List published messages (public URLs are also provided)
|
List archived messages
| ||||||
Paging and filtering (example) | 2 items per page, get first page (count starts from zero):
Retrieve messages that contain the word "test" in the subject field and order by ID. Note: search by text is case sensitive:
Retrieve only the messages with tags whose IDs are 1, 13, or 45 (at least one of them):
Retrieve only the messages with tags whose ID is 13 or names are customers, welcome message or hello, world (at least one of them):
Retrieve only the newsletter messages:
Retrieve only the SMTP+ messages:
|
|---|
Read message details
| Description | Retrieve the email details (content, settings, attachment) by specified id | ||
|---|---|---|---|
HTTP Method | GET | ||
URL | Retrieve the email details by specified id
|
Get attachment list for the specified message-id
| |||||
JSON request (example) | none | ||||
|---|---|---|---|---|---|
JSON response (example) | Message content
|
Message attachments
| ||||||
Paging and filtering (example) | 2 items per page, get first page (count starts from zero)
Retrieve messages that contain the word "test" in the subject field and order by ID. Note: search by text is case sensitive
|
|---|
Sending Queue Status
It is possible to retrieve the status of the sending queue for the outgoing messages by calling the following methods:
...
This method allows you to modify an existing message (content and settings).
Please note that
- The "Tags" field is mandatory, if you leave it empty the existing tags of that message are not modified. There is no way to clear all tags
- "Fields" parameter is optional
- "TrackingInfo > Protocols" field values are ignored if "TrackingInfo > Enabled" is set to false
| Description | Modify an existing message | ||||
|---|---|---|---|---|---|
HTTP Method | PUT | ||||
URL |
| ||||
JSON request (example) | Request data format is the same as the response of "GET /Console/List/{id_List}/Email/{id_Message}"
| ||||
JSON response (example) |
| ||||
Paging and filtering (example) | none |
Manage tags
| Description | Read available tags for a specified list | ||||||||
|---|---|---|---|---|---|---|---|---|---|
HTTP Method | GET, POST, PUT, DELETE | ||||||||
URL | Retrieve list tags:
Create a new tag:
Modify a tag:
Remove a list tag:
| ||||||||
JSON request (example) |
| ||||||||
JSON response (example) | GET method returns the retrieved tags list
POST and PUT methods return the full structure of the created/updated tag, e.g. {"Enabled":true,"Id":6,"Name":"my-new-tag"} An empty response is returned by DELETE method | ||||||||
Paging and filtering (example) | none |
Manage email attachments
MailUp messages support a maximum of five attachments. Each attachment is placed in a specified "slot": adding and removing an attachment means adding to a message "slot" or removing from it.
| Description | Read, add and remove message attachments | ||
|---|---|---|---|
HTTP Method | GET, POST, DELETE | ||
URL | Retrieve all the attachments of a specified message
|
Add an attachment to the message slot
|
Remove an attachment from a message slot
| |||
JSON request (example) | Only the POST method needs a request parameter. |
|---|
The attachment has to be Base64 encoded
| |||||
JSON response (example) | The GET method returns a list of the documents that are attached to the specified message. An empty array ([], not JSON format) is returned if no document is attached.
|
|---|
POST method returns the list of attachments after the command execution
|
DELETE method returns details about remaining attachments after deletion
| ||||||
Paging and filtering (example) | none |
|---|
Copy message
Description | Copy an existing message | ||||||||
|---|---|---|---|---|---|---|---|---|---|
HTTP Method | POST | ||||||||
URL |
| ||||||||
JSON request (example) | Copy message as-is:
Copy message modifying Notes:
Copy message modifying Subject:
Copy message modifying Subject and Notes:
| ||||||||
JSON response (example) |
|
Paging and filtering (example) |
|---|
Manage message online visibility
Description | Publish an existing message | |||||
|---|---|---|---|---|---|---|
HTTP Method | PUT | |||||
URL |
| |||||
JSON request (example) |
Publish a message:
|
Unpublish a message:
| ||
JSON response (example) | None | |
|---|---|---|
Paging and filtering (example) |
...
Send Email Messages
This section contains methods to send messages and to retrieve the history of sent messages.
You can enrich the calls to send messages using some querystring query string parameters, as follow:
| Querystring parameter | Description | Example |
|---|---|---|
| SenderName SenderAddress | Email messages are usually sent with the sender name and the sender name that |
| is specified as default settings for the MailUp list. As an alternative, you can specify a different sender for a certain sending by specifying "SenderName" and "SenderAddress" parameters. You have to provide both parameters |
| and not only one of them. | POST .../Send?SenderName='John Smith'&SenderAddress='smith@example.com' |
| DateTime | It is possible to specify an eventual UTC date/time for a deferred sending. |
send is scheduled you cannot modify it. | POST .../Send?datetime="2014-10-20 05:00:00Z" |
| It is possible to specify the value undefined for |
| the DateTime query string parameter. It means the message sending is scheduled as inactive. This option allows you to create a relationship between the messageand the recipients, as a snapshot: you can modify the message and when the message is ready you can decide to schedule the newsletter or to send it immediately. | POST .../Send?datetime="undefined" |
It is possible to omit the |
DateTime query string parameter (default) or set its value to now.
|
|
| POST .../Send POST .../Send?datetime="now" | |
| replyto | It is possible to specify an email address for a reply. | POST .../Send?replyto="replyto@yourdomain.it" |
| Note |
|---|
Message sending fails with HTTP 500 error if no authorized sender email nor sender email are provided. Ensure that sender name and sender email have been configured at list level (starting from MailUp version 8.6.1 the sender address has also to be a verified address) |
Send to all subscribers
| Description | Send a message to all list subscribers | ||
|---|---|---|---|
HTTP Method | POST | ||
URL | Use the default list sender
Use the sender that is provided by |
query string parameters
| |||
JSON request (example) | none | ||
|---|---|---|---|
JSON response (example) | See notes at the bottom of this page1
| ||
Paging and filtering (example) | none |
Send to list recipients filtering by groups
| Description | You may need to restrict your mailing to those recipients that belong to some MailUp groups or you may need to exclude the recipients of some groups. |
|---|
query string parameters with a valid value, the Send method allows including or excluding the recipients that belong to a list of specified groups. Here is how it works:
|
|
Please note that all the parameters' values must correspond to groups that belong to the MailUp list {id_List} specified in the REST endpoint. | |
HTTP Method | POST |
|---|---|
URL | Inclusion Include recipients that belong to one or more groups. |
recipient belongs to more than one group, it will be added just one time.
Exclusion Exclude subscribers that belong to one or more groups.
|
Inclusion and exclusion This is a case |
that merges the cases seen above: both |
inGroups and notInGroups are used. inGroups: |
at least one of the provided groups |
must belong to the specified MailUp list. Otherwise, the method returns a 500 error. In case of empty values, the inGroups parameter is ignored and the message is sent to all the MailUp list recipients. notInGroups: if the specified MailUp list does not contain all the provided groups, the method does not exclude any recipient and sends the newsletter to all the recipients filtered by the inGroups parameter.
| |||
JSON request (example) | none | ||
|---|---|---|---|
JSON response (example) | See notes at the bottom of this page1
| ||
Paging and filtering (example) | none |
Send to a group
Use the default list sender or a sender that is provided by querystring query string parameters (see example above)
| Description | Send a message to all subscribers of a specified group | ||
|---|---|---|---|
HTTP Method | POST | ||
URL |
| ||
JSON request (example) | none | ||
JSON response (example) | See notes at the bottom of this page1
| ||
Paging and filtering (example) | none |
Send to a recipient
Use the default list sender or a sender that is provided by querystring query string parameters (see example above)
| Description | Send a message to a single recipient | ||
|---|---|---|---|
HTTP Method | POST | ||
URL |
| ||
JSON request (example) |
| ||
JSON response (example) | See notes at the bottom of this page1
| ||
Paging and filtering (example) | none |
Retrieve sending history
An email message can be sent several times. This feature allows to retrieve retrieving details about each sending.
| Description | Retrieve information about the sent history | ||||
|---|---|---|---|---|---|
HTTP Method | GET | ||||
URL |
| ||||
JSON request (example) | none | ||||
JSON response (example) |
| ||||
Paging and filtering (example) | N/A |
- "Id" is the sending identifier. "Sent" is the size of the sending queue and may include either previously enqueued recipients or, despite of its name, discarded recipients (invalid or unprocessed). "InvalidRecipients" is expected to be always empty when sending to all list subscribers or to a group. "UnprocessedRecipients" contains a list of recipients that are excluded from sending due to a restriction (e.g. in case of a trial console account or when the rate-limiting described in API use policy is exceeded).
...
Use this endpoint to stop a specified sending. It works on scheduled or immediate sendings. It does not change the status of undefined / standby sendings.
You can perform a max 1 request every 30 seconds.
| Description | Stop a sending | ||
|---|---|---|---|
HTTP Method | POST | ||
URL |
| ||
JSON request (example) | none | ||
JSON response (example) | none | ||
Paging and filtering (example) | none |
Delete a sending
If you've already stopped the sending, use this endpoint to delete it. You MUST call the Stop a sending endpoint before to delete deleting scheduled or immediate / in-progress sendings. A standby sending does not require to be stopped.
You can perform 1 request every 30 seconds max.
| Description | Delete a sending | |||||
|---|---|---|---|---|---|---|
HTTP Method | DELETE | |||||
URL |
| |||||
JSON request (example) | none | |||||
JSON response (example) |
|
|
| |
Paging and filtering (example) | none |
|---|