Versions Compared
Key
- This line was added.
- This line was removed.
- Formatting was changed.
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Table of Contents |
---|
Getting started
...
Getting started
SMTP and API: same features
You can send transactional emails with MailUp in two ways:
- With our SMTP relay
- Using our API
The API provides the same features that are available with the newest version of our SMTP relay, SMTP+ v2
...
.
In addition, the performance, the aggregation policies and the usage restrictions (i.e. do not use it for promotional emails) are exactly the same as the ones enforced for SMTP+ v2.
...
Message header vs. JSON object
Although the features are largely the same, the way you access them is different. Parameters that are specified with message headers in SMTP+ v2, in the API are
...
handled as fields of
...
a JSON object that is passed to the web services. For more details about these parameters please check out the examples that are provided for SMTP+ v2
Best Practices
...
- Message aggregation: avoid using message aggregation types that create several dozens of messages per day in your admin console.
- CampaignCode: the new CampaignCode field is a great way to aggregate messages in
...
- a way that reduces the message count and - at the same time
...
- - provides more meaningful statistics. If you don't specify the CampaignCode value,
...
- the default value for the SMTP+ user applies (this value is set in the admin console).
- Returned value. Always check
...
- the value returned by the API: since most of the returned errors code are due to bad input parameters, any retry attempt will fail when returned code is HTTP 403.
...
Warnings
- Sending volume and speed. If you are using a trial or a developer account only a few messages can be sent, while for paying accounts such volume restrictions do not apply. In any case, delivery throughput cannot exceed the speed
...
- (messages per hour) that you purchased for your account.
- Password. If you change the password of your SMTP+ account, then any application based on it, API included, will stop working.
- Priority. Do not rely too much on the "Priority" field
...
- : many restrictions apply on it because its value is properly handled only at a specific stage of message workflow
...
- . There is no way to guarantee that the order based on priority value is kept at all delivery stages.
- No API error vs. successful message delivery. Please be aware that
...
- - just like with SMTP
...
- + - all methods used to send emails are asynchronous, hence a successful return code means that the request
...
- was correct and it has been added to a queue, but it does not guarantee
...
- message delivery
...
- . In other words, a successful return code indicates that queueing and processing was
...
- OK, but the specified recipient
...
- might still be unreachable or unsubscribed
...
- .
On this page... | |
---|---|
|
Authentication
Create a SMTP+ user
To access resources and to use the methods, you must have an active account with an enabled SMTP+ user (SMTP+ users have the "sNNNNN_NN" format).
Include credentials in the request
Usename and password must be included in each request through "User" parameter .
No Format |
---|
"User":{"Username":"YourSmtpPlusUsername","Secret":"YourSmtpPlusPassword"} |
An error may be returned when the SMTP+ user is blocked
...
. In this case you could use the "ListUserInfo" method to get more details about that user.
...
For example, there could be a billing issue.
Resources
...
Messages
This section includes the methods that can be used to send transactional emails.
Use
...
SendMessage
...
when you need to specify a completely different content for each message, while you can use
...
SendTemplate - and use merge tags - if you want to pick the body of an existing content and simply customize some of its parts.
...
The two method
...
provide the same level of
...
performance: pick the one that better fits your needs
...
.
SendMessage
Description | This method allows sending of a |
---|
...
transactional message to multiple recipients. This method is not intended for bulk mailings. The message content is passed as input with HTML code or plain text. The message may also include attachments and embedded images. | ||||||||||||||||||
HTTP Method | POST | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
URL | https://send.mailup.com/API/v2.0/messages/sendmessage | |||||||||||||||||
Reference |
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
| |||||||||||||||||||||
JSON request (example) |
| ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
JSON response (example) | Example of a successful response:{ "Status":"done",Example of error: { "Status":"error", |
SendTemplate
Description | This method allows sending of a transactional message to multiple recipients |
---|
...
. This method is not intended for bulk mailings. The message content (both HTML body and plain text) is obtained by specifying the unique ID of a |
...
message |
...
previously created and stored in the MailUp admin console. The message may also include attachments and embedded images. | ||||||||||||||||||
HTTP Method | POST | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
URL | https://send.mailup.com/API/v2.0/messages/sendtemplate | |||||||||||||||||
Reference |
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
| |||||||||||||||||||||
JSON request (example) |
| ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
JSON response (example) | Example of a successful response:{ "Status":"done", |
...
Example of error: { "Status":"error", |
Users
Use ListUserInfo to retrieve status details about current SMTP+ user or other SMTP+ users that belong to the same
...
List of a specified MailUp account.
ListUserInfo
Description | This method returns the list of SMTP+ users |
---|
...
that exist in the List of a specified MailUp account. |
...
Status details of each |
...
user are provided | ||||||
HTTP Method | POST | |||||
---|---|---|---|---|---|---|
URL | https://send.mailup.com/API/v2.0/users/listuserinfo | |||||
Reference |
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
|
...
| |||||
JSON request (example) | {"User":{"Username":"sNNNN_NN","Secret":"..."},"Username":"sMMMM_MM"} | ||||
---|---|---|---|---|---|
JSON response (example) | Example of a successful response:{ |
Example of error: { "Status":"error", |
Error codes
This table shows possible HTTP response statuses that can be returned by the API methods and the corresponding error code provided by the application (inside the response).
HTTP response code | Application Code | Description |
---|---|---|
200 | 0 | Ok |
400 | 1 | The operation |
...
failed. | ||
403 | 101 | The input is null. |
403 | 102 | The operation is not authorized. |
403 | 103 | The user is not enabled. |
403 | 104 | The user is blocked. |
403 | 105 | The user is blocked until this date. |
403 | 106 | The |
...
MailUp account |
...
cannot be found. | ||
403 | 107 | The |
...
MailUp account |
...
has been suspended. | ||
403 | 108 | The |
...
MailUp account |
...
has been deleted. | ||
403 | 109 | At least one recipient is required. |
403 | 110 | The sender is |
...
required. | ||
403 | 111 | The template |
...
...
cannot found. | |
403 | 112 |
...
The user has been deleted. |