Page Comparison

Getting started

SMTP or API? It's your

Getting started

SMTP or API? It's your choice

You can send transactional emails with MailUp in two ways:

With our SMTP relay (aka SMTP+)
Using our APIs

They

(details below on this page)

They provide virtually the same features. Specifically, the new transactional email API discussed in this section provides the same features that are available with the newest version of our SMTP relay, SMTP+ v2.In addition, the performance, the In addition, performances, scalability, the aggregation policies and the usage restrictions (i.e. do not use it for promotional emails) of the APIs 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,

. In fact, the two solutions share the backend architecture and the user authorization modules.

The main differences are the following:

in case you need only the basic feature, getting started with SMTP+ is usually easier because there are a lot of "ready to use" code snippets that help you implement a SMTP client
with APIs you can choose between providing the whole HTML code of the message or to refer an existing email template that may be personalized with merge tags. The SMTP relay does not support templates instead.
the way you access them is different. Parameters that are specified with message headers in SMTP+, 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+
with APIs you can take advantage of a set of additional methods for creating and retieving users

Best Practices

Message aggregation: avoid using message aggregation types that create several dozen messages per day in your MailUp 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.

Sending limitations

Please note Free trial accounts: please note that free trial accounts are limited to 25 messages sent per month. Once

Paying customers: once you become a paying customer, your sending speed and volume will be limited by the message frequency that you purchase have purchased (e.g. 5,000 messages per hour). See MailUp pricing for more.

Warnings

Password. If you change the password of your SMTP+ account, then any application based on it, API included, will stop

Input rate limit

The number of incoming requests must not exceed the frequency of messages you have purchased (e.g. if your MailUp subscription is set to 5,000 messages per hour avoid making more than 5,000 API calls to send messages). If you exceed this threshold, submission requests are likely to be rejected

Warnings

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 immediate message delivery. In other words, a successful return code indicates that queueing queuing and processing was OKsuccessful, but the specified recipient might still be unreachable or unsubscribed.
Caching applies. If you enable or disable an existing user, it may take up to 15' for the changes to take effect

On this page...

Table of Contents

User Management resources

Depending on the invoked method, user management resources may require different credentials and authentication methods.

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). You can create SMTP+ accounts and retrieve credentials:

from your platform, following what described in this page about SMTP Settings
calling a REST API endpoint

In this page we explain how to create a SMTP+ account using the REST API endpoint.

Anchorsmtpplus_getprioritycodesmtpplus_getprioritycodeGet priority codes

Description

Retrieve the list of priorities

HTTP Method

GET

URL

Code Block
https://services.mailup.com/api/v1.1/rest/ConsoleService.svc/Console/SmtpPlusPriorities

JSON request (example)

none

JSON response (example)

Code Block[ { "PriorityCode": 1, "PriorityName": "VeryHigh" }, { "PriorityCode": 2, "PriorityName": "High" }, { "PriorityCode": 3, "PriorityName": "Normal

type

References

Description

OAuth 2

Authenticating with OAuth v2

Standard OAuth 2 with access and refresh tokens. In the request you must add the following header:

No Format
Authorization: Bearer {access_token}

Note: OAuth 2 requires the MailUp account credentials, not SMTP+ username and password

SMTP+ credentials in the request body

SMTP relay service

SMTP+ username and password must be included in each request through the "User" parameter inside the request body.

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.

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" name format). You can create SMTP+ accounts and retrieve their credentials:

from within the MailUp platform. See: SMTP Settings
calling a REST API endpoint

In this page we explain how to create a SMTP+ account using the REST API endpoint.

Anchor
smtpplus_getprioritycode
smtpplus_getprioritycode
Get priority codes

Description

Service method to get the enumerated types of the available priority levels

Authentication

OAuth 2

HTTP Method

GET

URL

Code Block
https://services.mailup.com/api/v1.1/rest/ConsoleService.svc/Console/SmtpPlusPriorities

JSON request (example)

none

JSON response (example)

Expand

Code Block
[ { "PriorityCode": 1, "PriorityName": "VeryHigh" }, { "PriorityCode":

4

2,
        "PriorityName": "

Low

High"
    },
    {

"PriorityCode": 5, "PriorityName": "VeryLow" } ]

 "PriorityCode": 3,
        "PriorityName": "Normal"
    },
    {
        "PriorityCode": 4,
        "PriorityName": "Low"
    },
    {
        "PriorityCode": 5,
        "PriorityName": "VeryLow"
    }
]

Paging and filtering (example)

none

Create a new user

Description

Before creating a SMTP+ user you have to define one or more trusted senders email and/or one or more trusted domains. To retrieve the list of trusted emails please refer to this page. Remember that you can create a SMTP+ user only if all the trusted senders you provide in the TrustedSenders field have the StatusCode property equals to 1 (Confirmed): you can find this information here.

Authentication

OAuth 2

HTTP Method

POST

URL

Code Block
https://services.mailup.com/api/v1.1/rest/ConsoleService.svc/Console/List/{id_list}/SmtpPlus

JSON request (example)

Code Block
{ "IsEnabled": true, "Note": "Your notes", "PriorityCode": 2, "TrustedDomains": ["yourtrusteddomain.com"], "TrustedSenders": ["you@yourtrusteddomain.com"] }

JSON response (example)

Expand

title	Click here to see an example of successful response...

If your request is correct, you receive the following response:

Code Block

200 OK

{
    "CreationDate": "2017-06-30 10:32:38Z",
    "IdList": 2,
    "IsEnabled": true,
    "Note": "",
    "Password": "ut0ee?k9jv",
    "PriorityCode": 3,
    "SmtpPlusEncryption": "NONE, STARTTLS",
    "SmtpPlusPort": "25, 80, 1025-5000",
    "SmtpPlusServer": "in.smtpok.com",
    "TrustedDomains": [
		"yourtrusteddomain.com"
	],
    "TrustedSenders": [
        ""you@yourtrusteddomain.com""
    ],
    "UpdateDate": "2017-06-30 10:32:38Z",
    "Username": "sXXXXX_XX"
}

Expand

title	Click here to check the error codes

You receive a 400 Bad request response containing the reason into the Error Description field when you try to create an account with:

a missing or empty request body
a wrong PriorityCode value (to retrieve the list of valid priority codes please refer to the Get priority codes paragraph)
both the fields TrustedDomains and TrustedSenders are empty
at least an email address not trusted into the TrustedSenders field
at least a domain address not trusted into the TrustedDomains field

You receive a 403 Forbidden response, containing the reason in the Error Description field, when the SMTP+ user management option is not enabled in your platform.

A HTTP 500 error is returned if the specified sender address has raised a warning in the deliverability checkup process (refer to "Account settings > Deliverability checkup")

Paging and filtering (example)

none

Create your account

Reset password

If you need more information about MailUp REST API OAuth 2.0 authorization process, please refer to this page.

Description

Create a SMTP+ account.

To create a SMTP+ account you have to provide one or more trusted senders email and/or one or more trusted domains. To retrieve the list of trusted emails please refer to thispage. Remember that you can create an SMTP+ account only if all the trusted senders you provide by TrustedSenders field have got the StatusCode property equals to 1 (Confirmed): you can find this information here.

To propertly attemps this request, you need an access_token and include it into the Authorization header as shown below:

Code Block
Authorization: Bearer {access_token}

Reset the password for the specified SMTP+ user. MailUp is in charge of creating a new password and providing it in the response body

Authentication

OAuth 2

HTTP Method

POST

URL

Code Block
https://services.mailup.com/api/v1.1/rest

/ConsoleService.svc/Console/List/{id_list}/SmtpPlus

JSON request (example)

Code Block{ "IsEnabled": true, "Note": "Your notes", "PriorityCode": 2, "TrustedDomains": ["yourtrusteddomain.com"], "TrustedSenders": ["you@yourtrusteddomain.com"]

/ConsoleService.svc/Console/List/{ID_LIST}/SmtpPlus/Reset

JSON request (example)

Code Block
{ "Username": "<username>" }

JSON response (example)

If your request is correct, you'll receive the following response

Code Block
200 OK { "CreationDate": "2017-

06

08-

30

10:32:38Z"

07:42:45Z",
    "IdList": 2,
    "

IdList

IsEnabled":

2

true,
    "

IsEnabled

IsTrusted": true,
    "Note": "My notes",
    "Password": "

ut0ee?k9jv

<the new password>",
    "PriorityCode": 3,
    "SmtpPlusEncryption": "NONE, STARTTLS",
    "SmtpPlusPort": "25, 80, 1025-5000",
    "SmtpPlusServer": "

in

fast.smtpok.com",
    "TrustedDomains": [

"yourtrusteddomain.com" ]

],
    "TrustedSenders": [
        "you@yourtrusteddomain.com"
    ],
    "UpdateDate": "2017-08-11 08:44:50Z",
    "

TrustedSenders

Username":

[

"<username>"
}

If something goes wrong:

Code Block
404 NotFound { "ErrorCode"

you@yourtrusteddomain.com

: "404"

]

,
    "

UpdateDate

ErrorDescription": "

2017-06-30 10:32:38Z

Account not found.",
    "

Username

ErrorName": "

sXXXXX_XX" }

You'll receive a 400 Bad request response containing the reason into the Error Description field when you try to create an account with:

a missing or empty request body
a wrong PriorityCode value (to retrieve the list of valid priority codes please refer to the Get priority codes paragraph)
both the fields TrustedDomains and TrustedSenders are empty
at least an email address not trusted into the TrustedSenders field
at least a domain address not trusted into the TrustedDomains field

You'll receive a 403 Forbidden response, containing the reason into the Error Description field, when the SMTP+ user management option wasn't enabled to your platform.

Paging and filtering (example)

none

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 methods provide the same level of performance: pick the one that better fits your needs.

Info

title	Using a reply-to address different from the sender address

The use of a reply-to address different from the FROM email address must be enabled by MailUp. If you need this, please contact our support team by writing an email to support@mailup.com.

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 MethodPOSTURLhttps://send.mailup.com/API/v2.0/messages/sendmessage
Reference Expand

title	Click here to learn more about request parameters

The method takes as input the document JSON or XML that has the structure MessageDTO defined in the tables below.

MessageDTO
Parameter	Type	Description
Subject	String	the subject of the message
Html	HtmlDTO	HTML part of the message (specify only the HTML inside the BODY tag)
Text	String	the plain text part of the message
From	EmailAddressDTO	the sender's name and email address
To	List<EmailAddressDTO>	the list of recipientsin Toheader
Cc	List<EmailAddressDTO>	the list of recipients in Cc header
Bcc	List<EmailAddressDTO>	the list of recipients in Bcc
ReplyTo	String	the email address to be added into Reply-To header
CharSet	String	the charset of the message body
ExtendedHeaders	List<NameValueDTO>	list of custom headers (only SMTP headers that are approved by MailUp will be added)
Attachments	List<MessagePartDTO>	list of attachments
EmbeddedImages	List<MessagePartDTO>	list of embedded images
XSmtpAPI	XSmtpAPIDTO	the X-SMTPAPI header value, used for custom aggregations and configurations
User	SmtpUserDTO	the SMTP+ user credentials: the API uses the same credentials as the SMTP relay

HtmlDTO
Parameter	Type	Description
DocType	String	the DOCTYPE directive
Head	String	the head content
Body	String	the body content
BodyTag	String	the body tag, default is "< body>"

EmailAddressDTO
Parameter	Type	Description
Name	String	the name
Email	String	the email address

NameValueDTO
Parameter	Type	Description
N	String	the name of the parameter
V	String	the value of the parameter

MessagePartDTO
Parameter	Type	Description
Filename	String	the file name
ContentId	String	the Content-Id value
Body	Array of Byte	the array of byte of the content

XSmtpAPIDTO
Parameter	Type	Description
CampaignName	String	the name used for the aggregated campaign
CampaignCode	String	the campaign code which determines the aggregation
Header	Boolean	add or not the MailUp header to the message
Footer	Boolean	add or not the MailUp footer to the message
ClickTracking	Boolean	enable click tracking
ViewTracking	Boolean	enable view tracking
Priority	Integer	set the priority of the message (1 high - 5 low )
Schedule	DateTime	schedule date and time of when it should be sent
DynamicFields	List<NameValueDTO>	list of merge tags and recipient fields
CampaignReport	String	name of the aggregated campaign report
SkipDynamicFields	Boolean	skip merge tags evaluation

SmtpUserDTO
Parameter	Type	Description
Username	String	username
Secret	String	password

Expand

title	Click here to learn more about response parameters

SendResponseDTO
Parameter	Type	Description
Status	String	the status of the response can be "done" or "error"
Code	String	the result code (see the Error Code table)
Message	String	the result message

JSON request (example)

Expand

{
 "Html":
 {
 "DocType":null,
 "Head":null,
 "Body":"<div>Hello Mr. [firstname] [lastname] !!!</div><br><img width=\"600\" height=\"397\" src=\"cid:img001\">",
 "BodyTag":"<body>"
 },
 "Text":"Hello world!!!",
 "Subject":"Hello friend!",
 "From":{"Name":"Test User","Email":"test@mailup.it"},
 "To":[{"Name":"Massimo","Email":"info@mailup.it"}],
 "Cc":[],
 "Bcc":[],
 "ReplyTo":null,
 "CharSet":"utf-8",
 "ExtendedHeaders":null,
 "Attachments":null,
 "EmbeddedImages":
 [
 {
 "Filename":"Image.jpg",
 "ContentId":"img001",
 "Body":"..."
 }
 ],
 "XSmtpAPI":
 {
 "CampaignName":"Test Campaign",
 "CampaignCode":"1001",
 "Header":false,
 "Footer":true,
 "ClickTracking":null,
 "ViewTracking":null,
 "Priority":null,
 "Schedule":null,
 "DynamicFields":[{"N":"firstname","V":"Mario"},{"N":"lastname","V":"Rossi"}],
 "CampaignReport":null,
 "SkipDynamicFields":null
 },
 "User":{"Username":"sNNNNN_NN","Secret":"..."}
}

JSON response (example)Example of a successful response:

"Status":"done",
 "Code":"0",
 "Message":"Ok"
}

Example of error:

"Status":"error",
 "Code":"102",
 "Message":"The operation is not authorized."
}

SendTemplate

Description

This method allows sending of a transactional message to multiple recipients, taking advantage of placeholders to customize content. 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.

Note
Only lowercase placeholders must be used in the referenced messages. If you use capital letters (e.g. "Dear [FirstName]", the text is not replaced

HTTP MethodPOSTURLhttps://send.mailup.com/API/v2.0/messages/sendtemplate Reference Expand

title	Click here to learn more about request parameters

TemplateDTO
Parameter	Type	Description
Subject	String	the subject of the message
TemplateId	Integer	Numeric ID of the MailUp message whose content has to be used. It only accepts messages that belong to the same List in which the SMTP+ user was created
From	EmailAddressDTO	the sender's name and email address
To	List<EmailAddressDTO>	the list of recipientsin Toheader
Cc	List<EmailAddressDTO>	the list of recipients in Cc header
Bcc	List<EmailAddressDTO>	the list of recipients in Bcc
ReplyTo	String	the email address to be added into Reply-To header
CharSet	String	the charset of the message body
ExtendedHeaders	List<NameValueDTO>	list of custom headers (only SMTP headers that are approved by MailUp will be added)
Attachments	List<MessagePartDTO>	list of attachments
EmbeddedImages	List<MessagePartDTO>	list of embedded images
XSmtpAPI	XSmtpAPIDTO	the X-SMTPAPI header value, used for custom aggregations and configurations
User	SmtpUserDTO	the SMTP+ user credentials

See the SendMessage reference for the definition of the others DTOs (EmailAddressDTO, NameValueDTO, ...)

Expand

title	Click here to learn more about response parameters

SendResponseDTO
Parameter	Type	Description
Status	String	the status of the response can be "done" or "error"
Code	String	the result code (see the Error Code table)
Message	String	the result message

JSON request (example) Expand

"TemplateId":694,
 "Subject":"Test message from template",
 "From":{"Name":"Test User","Email":"test@example.com"},

"To":[{"Name":"Max","Email":"info@example.com"}],
"Cc":[],
"Bcc":[],
"ReplyTo":null,
"CharSet":"utf-8",
"ExtendedHeaders":null,
"Attachments":null,
"EmbeddedImages":null,
"XSmtpAPI":null

NotFound",
    "ErrorStack": ""
}

Paging and filtering (example)

none

Get SMTP+ 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

Authentication

SMTP+ credentials in the request body

HTTP Method

POST

URL

https://send.mailup.com/API/v2.0/users/listuserinfo

Reference

Expand

title	Click here to learn more about request parameters

The request must contain the user's credentials and an optional username to query

ListUsersDTO
Parameter	Type	Description
User	SMTPUserDTO	the calling User
Username	String	optional User from which to read the profile, if omitted the method returns all users

See the SendMessage reference for the definition of SMTPUserDTO

Expand

title	Click here to learn more about response parameters

The response is given by a JSON or XML document that has the structure of a list of users information ( List<UserInfoDTO>).

UserInfoDTO
Parameter	Type	Description
Username	SMTPUserDTO	the username
IdConsole	long	the MailUp account ID
IdList	long	the List Id within that account
IsEnabled	bool	true if the user is enabled
Priority	int	default priority setting for messages sent by this user
Note	string	admin notes
CreationDate	datetime	creation date
UpdateDate	datetime	last updated date
DomainList	string	list of allowed domains
SenderList	string	list of allowed email senders
BlockUntil	datetime	date until the user is blocked
AdminBlock	bool	true if the user is blocked by the system administrator

JSON request (example)

{"User":{"Username":"sNNNN_NN","Secret":"..."},"Username":"sMMMM_MM"}

JSON response (example)

Example of a successfulresponse:

{
 "Status":"done",
 "Code":"0",
 "Message":"Ok",
 "UserList":
 [
 {
 "Username":"sMMMM_MM",
 "IdConsole":123,
 "IdList":1,
 "IsEnabled":true,
 "Priority":3,
 "Note":"",
 "CreationDate":"2015-03-31T12:12:04",
 "UpdateDate":"2015-03-31T12:12:34",
 "DomainList":"",
 "SenderList":"",
 "BlockUntil":"0001-01-01T00:00:00",
 "AdminBlock":false
 }
 ]
}

Example of error:

"Status":"error",
 "Code":"112",
 "Message":"User is deleted."
}

Send resources

All the send resources are accessed using SMTP+ credentials

Authentication type

References

Description

SMTP+ credentials in the request body

SMTP relay service

SMTP+ Username and password must be included in each request through the "User" parameter inside the request body.

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.

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 methods provide the same level of performance: pick the one that better fits your needs.

Info

title	Using a reply-to address different from the sender address

The use of a reply-to address different from the FROM email address must be enabled by MailUp. If you need this, please contact our support team by writing an email to support@mailup.com.

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.

Authentication

SMTP+ credentials in the request body

HTTP Method

POST

URL

https://send.mailup.com/API/v2.0/messages/sendmessage

Reference

Expand

title	Click here to learn more about request parameters

The method takes as input the document JSON or XML that has the structure MessageDTO defined in the tables below.

MessageDTO
Parameter	Type	Description
Subject	String	the subject of the message
Html	HtmlDTO	HTML part of the message (specify only the HTML inside the BODY tag)
Text	String	the plain text part of the message
From	EmailAddressDTO	the sender's name and email address
To	List<EmailAddressDTO>	the list of recipientsin Toheader
Cc	List<EmailAddressDTO>	the list of recipients in Cc header
Bcc	List<EmailAddressDTO>	the list of recipients in Bcc
ReplyTo	String	the email address to be added into Reply-To header
CharSet	String	the charset of the message body
ExtendedHeaders	List<NameValueDTO>	list of custom headers (only SMTP headers that are approved by MailUp will be added)
Attachments	List<MessagePartDTO>	list of attachments
EmbeddedImages	List<MessagePartDTO>	list of embedded images
XSmtpAPI	XSmtpAPIDTO	the X-SMTPAPI header value, used for custom aggregations and configurations. You can use this parameter to overwrite, for a specific message, some of the settings that are defined at SMTP+ user level
User	SmtpUserDTO	the SMTP+ user credentials: the API uses the same credentials as the SMTP relay

HtmlDTO
Parameter	Type	Description
DocType	String	the DOCTYPE directive
Head	String	the head content
Body	String	the body content
BodyTag	String	the body tag, default is "< body>"

EmailAddressDTO
Parameter	Type	Description
Name	String	the name
Email	String	the email address

NameValueDTO
Parameter	Type	Description
N	String	the name of the parameter
V	String	the value of the parameter

MessagePartDTO
Parameter	Type	Description
Filename	String	the file name
ContentId	String	the Content-Id value
Body	Array of Byte	the array of byte of the content

XSmtpAPIDTO
Parameter	Type	Description
CampaignName	String	the name used for the aggregated campaign
CampaignCode	String	the campaign code which determines the aggregation
Header	Boolean	add or not the MailUp header to the message
Footer	Boolean	add or not the MailUp footer to the message
ClickTracking	Boolean	enable click tracking
ViewTracking	Boolean	enable view tracking
Priority	Integer	set the priority of the message (1 high - 5 low )
Schedule	DateTime	schedule date and time of when it should be sent Time must be specified with the CET Time zone because it is compared with our servers' time settings. Examples: "Schedule": "2021-10-06T17:35+02:00" (with Daylight Saving Time) "Schedule": "2021-12-25T17:35+01:00" (without DST) Please note that an immediate sendout is done if the specified scheduling is before the current date time
DynamicFields	List<NameValueDTO>	list of merge tags and recipient fields
CampaignReport	String	name of the aggregated campaign report
SkipDynamicFields	Boolean	skip merge tags evaluation

SmtpUserDTO
Parameter	Type	Description
Username	String	username
Secret	String	password

Expand

title	Click here to learn more about response parameters

SendResponseDTO
Parameter	Type	Description
Status	String	the status of the response can be "done" or "error"
Code	String	the result code (see the Error Code table)
Message	String	the result message

JSON request (example)

Expand

{
 "Html":
 {
 "DocType":null,
 "Head":null,
 "Body":"<div>Hello Mr. [firstname] [lastname] !!!</div><br><img width=\"600\" height=\"397\" src=\"cid:img001\">",
 "BodyTag":"<body>"
 },
 "Text":"Hello world!!!",
 "Subject":"Hello friend!",
 "From":{"Name":"Test User","Email":"test@mailup.it"},
 "To":[{"Name":"Massimo","Email":"info@mailup.it"}],
 "Cc":[],
 "Bcc":[],
 "ReplyTo":null,
 "CharSet":"utf-8",
 "ExtendedHeaders":null,
 "Attachments":null,
 "EmbeddedImages":
 [
 {
 "Filename":"Image.jpg",
 "ContentId":"img001",
 "Body":""
 }
 ],
 "XSmtpAPI":
 {
 "CampaignName":"Test Campaign",
 "CampaignCode":"1001",
 "Header":false,
 "Footer":true,
 "ClickTracking":null,
 "ViewTracking":null,
 "Priority":null,
 "Schedule":"2021-09-14T17:58+02:00",
 "DynamicFields":[{"N":"firstname","V":"Mario"},{"N":"lastname","V":"Rossi"}],
 "CampaignReport":null,
 "SkipDynamicFields":null
 },
 "User":{"Username":"sNNNNN_NN","Secret":"..."}
}

JSON response (example)

Example of a

successfulresponse

successful response:

"Status":"done",
 "Code":"0",
 "Message":"Ok"
}

Example of error:

"Status":"error",
 "Code":"

0

102",
 "Message":"

Ok

The operation is not authorized."
}

Example of error:

"Status":"error",
 "Code":"111",
 "Message":"The template is not found."
}

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

DescriptionThis method returns the list of SMTP+ users that exist in the List of a specified MailUp account. Status details of each user are provided

SendTemplate

Description

This method allows sending of a transactional message to multiple recipients, taking advantage of placeholders to customize content. 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.

Note
Only lowercase placeholders must be used in the referenced messages. If you use capital letters (e.g. "Dear [FirstName]", the text is not replaced.

If you edit an email message already sent, wait 15 minutes before sending out the modified message. This time is needed to update the cache

Authentication

SMTP+ credentials in the request body

HTTP Method

POST

URL

https://send.mailup.com/API/v2.0/

users

messages/

listuserinfo Expand

title	Click here to learn more about response parameters

The response is given by a JSON or XML document that has the structure of a list of users information ( List<UserInfoDTO>).

UserInfoDTOParameterTypeDescriptionUsernameSMTPUserDTOthe usernameIdConsolelongthe MailUp account IDIdListlongthe List Id within that accountIsEnabledbooltrue if the user is enabledPriorityintdefault priority setting for messages sent by this userNotestringadmin notesCreationDatedatetimecreation dateUpdateDatedatetimelast updated dateDomainListstringlist of allowed domainsSenderListstringlist of allowed email sendersBlockUntildatetimedate until the user is blockedAdminBlockbooltrue if the user is blocked by the system administrator

sendtemplate

Reference

Expand

title	Click here to learn more about request parameters

The request must contain the user's credentials and an optional username to query

ListUsersDTO
Parameter	Type	Description
User	SMTPUserDTO	the calling User
Username	String	optional User from which to read the profile, if omitted the method returns all users

See the SendMessage reference for the definition of SMTPUserDTO

TemplateDTO
Parameter	Type	Description
Subject	String	the subject of the message
TemplateId	Integer	Numeric ID of the MailUp message whose content has to be used. It only accepts messages that belong to the same List in which the SMTP+ user was created
From	EmailAddressDTO	the sender's name and email address
To	List<EmailAddressDTO>	the list of recipientsin Toheader
Cc	List<EmailAddressDTO>	the list of recipients in Cc header
Bcc	List<EmailAddressDTO>	the list of recipients in Bcc
ReplyTo	String	the email address to be added into Reply-To header
CharSet	String	the charset of the message body
ExtendedHeaders	List<NameValueDTO>	list of custom headers (only SMTP headers that are approved by MailUp will be added)
Attachments	List<MessagePartDTO>	list of attachments
EmbeddedImages	List<MessagePartDTO>	list of embedded images
XSmtpAPI	XSmtpAPIDTO	the X-SMTPAPI header value, used for custom aggregations and configurations You can use this parameter to overwrite, for a specific message, some of the settings that are defined at SMTP+ user level
User	SmtpUserDTO	the SMTP+ user credentials

See the SendMessage reference for the definition of the others DTOs (EmailAddressDTO, NameValueDTO, ...)

Expand

title	Click here to learn more about response parameters

SendResponseDTO
Parameter	Type	Description
Status	String	the status of the response can be "done" or "error"
Code	String	the result code (see the Error Code table)
Message	String	the result message

JSON request (example)

Expand
{

"User

"TemplateId":694,
 "Subject":"Test message from template",
 "From":{"

Username

Name":"

sNNNN_NN

Test User","

Secret

Email":"test@example.

..

com"},

Username

To":

"sMMMM_MM"}JSON response (example)Example of a successfulresponse:{
"Status

[{"Name":"

done

Max",

Code

Email":"

0

info@example.com"}],
 "

Message

Cc":

"Ok"

[],
 "

UserList

Bcc":

[],

{

"ReplyTo":null,
 "

Username

CharSet":"

sMMMM_MM

utf-8",
 "

IdConsole

ExtendedHeaders":

123

null,
 "

IdList

Attachments":

1

null,
 "

IsEnabled

EmbeddedImages":

true

null,
 "

Priority

XSmtpAPI":

3

null,
 "

Note

User":{"

",
"CreationDate":"2015-03-31T12:12:04",
"UpdateDate":"2015-03-31T12:12:34",
"DomainList":"",
"SenderList":"

Username":"sNNNNN_NN","Secret":"..."}
}

JSON response (example)

Example of a successfulresponse:

"Status":"done",
 "

BlockUntil

Code":"

0001-01-01T00:00:00

0",
 "

AdminBlock

Message":

false

"Ok"

]
}

Example of error:

"Status":"error",
 "Code":"

112

111",
 "Message":"

User

The template is not

deleted

found."
}

Error codes

This table shows possible HTTP response statuses lists the response codes that can be returned by the API methods and the corresponding error code provided by the application (inside the response)methods whose authentication method consists of SMTP+ credentials in the request body.

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

leastone

least one recipient is required.
403	110	The sender is required.
403	111	The template cannot found.
403	112	The user has been deleted.

Versions Compared

Old Version 28

New Version Current

Key

Getting started

Getting started

SMTP or API? It's your choice

Message header vs. JSON object

Best Practices

Best Practices

Sending limitations

Warnings

Input rate limit

Warnings

User Management resources

Create a SMTP+ user

Create a SMTP+ user

Anchor
smtpplus_getprioritycode
smtpplus_getprioritycode
Get priority codes

Create a new user

Reset password

Include credentials in the request

Resources

Messages

SendMessage

SendTemplate

Get SMTP+ users

ListUserInfo

Send resources

Messages

SendMessage

Users

ListUserInfo

SendTemplate

Error codes