This page provides you information about how to use MailUp REST API to create email messages and to send them to specified recipients.
On this page:
Email messages
An email message is always created inside the environment of a MailUp list, so it cannot be managed outside of that list.
Please note that, when creating a new email message, any referenced tag or attachment must be created in advance for that list.
Create a message
Important about creating a new message
- any referenced tag or attachment must be created in advance for that list
- to enable use of dynamic fields, which are disabled by default, choose one of these options:
- specify at least one default value in the "Fields" parameter (as in the sample request below);
- use the EnableDynamicFields method;
- use the request property UseDynamicField: true
Description | Create a new email message |
---|---|
HTTP Method | POST |
URL | Create a message https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email |
JSON request (example) | |
JSON response (example) | { "CreationDate": "2016-09-16 15:57:35Z", "Notes": "", "Subject": "Monthly Newsletter 4", "idList": 2, "idMessage": 1060 }
|
Paging and filtering (example) |
|
Enable Dynamic fields
Description | Enable or disable dynamic fields |
---|---|
HTTP Method | PUT |
URL | Create a message https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list/{id_List}/Email/{id_Message}/EnableDynamicFields/{enable} |
JSON request (example) | Enable or Disable https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list//Email/1061/EnableDynamicFields/true https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list//Email/1061/EnableDynamicFields/false
|
JSON response (example) | Message details are returned
|
Paging and filtering (example) |
|
List Messages
Description | Retrieve email messages of specified list |
---|---|
HTTP Method | GET |
URL | Retrieve all email messages of that list GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Emails
Retrieve only email messages that have been published (i.e. with public visibility, see details) 1 GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Online/Emails
Retrieve only email messages that have been archived (see details) 1 GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Archived/Emails
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 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 https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}
Get attachment list for the specified message id https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Attachment |
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:
1) status of ongoing sendings: GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Email/Sendings/Immediate
2) status of waiting sendings: GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Email/Sendings/Deferred
3) status of sending to be planned: GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Email/Sendings/Undefined
Moreover, it is possible to retrieve the first available date to send a specific sending:
where {id_sending} is the unique identifier of the sending to consider. The result is the date UTC date specified with the format described in the section 'Type and cast definition' of this page: "Paging and filtering".
Update message
This method allows you to modify an existing message (content and settings).
Please note that
- "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 | https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message} |
JSON request (example) | Request data format is the same as the response of "GET /Console/List/{id_List}/Email/{id_Message}" |
JSON response (example) | {"Subject":"Monthly Newsletter!","idList":2,"idMessage":24} |
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: GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Tags Create a new tag: POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Tag Modify a tag: PUT https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Tag/{id_Tag} Remove a list tag: DELETE https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Tag/{id_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 GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Attachment
Add an attachment to message slot POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Attachment/{Slot}
Remove an attachment from a message slot DELETE https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Attachment/{Slot} |
JSON request (example) | Only POST method needs a request parameter. Attachment has to be Base64 encoded |
JSON response (example) | GET method returns a list of the documents that are attached to 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 | Create a message https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list/{id_List}/Email/{id_Message} |
JSON request (example) | Copy message as is: POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list/2/Email/135 Copy message modifying Notes: POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list/2/Email/135 {"Notes": "This is a new note!!!"} |
JSON response (example) | { "CreationDate": "2017-08-30 15:24:07Z", "Notes": "This is a new note!!!", "Subject": "Important email", "idList": 1, "idMessage": 136 }
|
Paging and filtering (example) |
|
Manage message online visibility
Description | Publish an existing message |
---|---|
HTTP Method | PUT |
URL | Create a message https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list/{id_List}/Email/{id_Message}/OnlineVisibility |
JSON request (example) | Puslish a message: PUT https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list/2/Email/135/OnlineVisibility true Unpuslish a message: PUT https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/list/2/Email/135/OnlineVisibility false |
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 parameters, as follow:
Querystring parameter | Description | Example |
---|---|---|
SenderName SenderAddress | Email messages are usually sent with the sender name and the sender name that are 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. | POST .../Send?datetime="2014-10-20 05:00:00Z" |
It is possible to specify the value undefined for datetime querystring parameter. It means the message sending is scheduled as inactive. This option allows you to create a relationship between the message and 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 querystring parameter (default) or set its value to now. Important tip! As you can immagine, if you use this option to send to some recipients and you use the method to send to a single recipient now, you append a lot of items to your sending queue. Every time an item is processed, it starts a verification process that requires some seconds: if you enqueue 10.000 items your sending period could be very long. So, if you need to send to a single recipient we suggest to use our Transactional Emails APIs; otherwise, please use list or groups to enqueue multi-recipients items to the sending queue. | POST .../Send POST .../Send?datetime="now" | |
replyto | It is possible to specify an email address for reply. | POST .../Send?replyto="replyto@yourdomain.it |
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 POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Send Use the sender that is provided by querystring parameters POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Send?SenderName='{name}'&SenderAddress='{email}' |
JSON request (example) | none |
JSON response (example) | See notes at the bottom of this page1 {"InvalidRecipients":[],"Sent":7,"UnprocessedRecipients":[],"idMessage":24} |
Paging and filtering (example) | none |
Send to list subscribers filtering by groups
Description | Send a message to list subscribers filtering by groups. The method allows subscribers inclusion and exclusion by groups.
The method checks if the selected list contains the provided groups. |
---|---|
HTTP Method | POST |
URL | Inclusion Include subscribers by one or more groups. POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Send?inGroups=12 POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Send?inGroups=12,23,45 Exclusion Exclude subscribers by one or more groups. POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Send?notInGroups=12 POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Send?notInGroups=12,23,45
Inclusion and exclusion Include and exclude subscribers by one or more groups. POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Send?notInGroups=12¬InGroups=89,90 POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/Send?notInGroups=12,23,45¬InGroups=89 |
JSON request (example) | none |
JSON response (example) | See notes at the bottom of this page1 {"InvalidRecipients":[],"Sent":7,"UnprocessedRecipients":[],"idMessage":24} |
Paging and filtering (example) | none |
Send to a group
Use the default list sender or a sender that is provided by querystring parameters (see example above)
Description | Send a message to all subscribers of specified group |
---|---|
HTTP Method | POST |
URL | POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Group/{id_Group}/Email/{id_Message}/Send |
JSON request (example) | none |
JSON response (example) | See notes at the bottom of this page1 {"InvalidRecipients":[],"Sent":3,"UnprocessedRecipients":[],"idMessage":30} |
Paging and filtering (example) | none |
Send to a recipient
Use the default list sender or a sender that is provided by querystring parameters (see example above)
Description | Send message to a single recipient |
---|---|
HTTP Method | POST |
URL | POST https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/Email/Send |
JSON request (example) | { "Email":"cheetah@jungle.net", "idMessage":30 } |
JSON response (example) | See notes at the bottom of this page1 {"InvalidRecipients":[],"Sent":3,"UnprocessedRecipients":[],"idMessage":30} |
Paging and filtering (example) | none |
Retrieve sending history
An email message can be sent several times. This feature allows to retrieve details about each sending.
Description | Retrieve information about sent history |
---|---|
HTTP Method | GET |
URL | GET https://services.mailup.com/API/v1.1/Rest/ConsoleService.svc/Console/List/{id_List}/Email/{id_Message}/SendHistory |
JSON request (example) | none |
JSON response (example) | |
Paging and filtering (example) | N/A |
- "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)
when creating a new email message, any referenced tag or attachment must be created in advance for that list.