Knowledgebase

Sending an email message

Example of json data for a request:

{
  "from_email":"alice@example.org",
  "from_name": "Alice",
  "to": "bob@example.org",
  "subject": "Hello",
  "text": "Hello, Bob!",
  "html": "<h1>Hello, Bob!</h1>",
  "payment": "credit",
  "smtp_headers": {
    "Client-Id": "123"
  }
}

An example of the request itself could look like this:

curl -X POST https://api.msndr.net/v1/email/messages \
     -H 'Content-Type: application/json'        \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -d '...JSON...'

POST method and /email/messages link used here

An example of the response to the request if it was successful:

{
  "id":1,
  "from_email":"alice@example.org",
  "from_name":"Alice",
  "to":"bob@example.org",
  "subject":"Hello",
  "text":"Hello, Bob!",
  "html":"<h1>Hello, Bob!</h1>",
  "attachments": [],
  "status":"queued",
  "events": {
    "open": 1,
    "redirect": {
      "http://foo.com": 2,
      "http://bar.com": 3
    },
    "spam": 1,
    "unsubscribe": 1
  }
}

You can also send a message with attachments. An example of such a request is:

curl -X POST https://api.msndr.net/v1/email/messages \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -F from_email=from@example.com             \
     -F to=to@example.com                       \
     -F subject='Mail with attachments'         \
     -F text='Hello world'                      \
     -F attachments[]=@/path/to/file1           \
     -F attachments[]=@/path/to/file2           \
     -F smtp_headers[Client-Id]=123

The parameters from_email (the email address from which the message is sent), to (the email address of the recipient), subject (the subject) are mandatory. From_name (the name from which the message is sent) is an optional parameter. One of the text or html parameters must also be set. Attachments is an array of attachments. It is only supported in multipart/form-data content type requests.

Payment is a way of rating the message. It can take the values:

1.subscriber_priority
2.credit_priority
3.subscriber
4.credit

If you don't specify a value, it will be subscriber_priority by default.

smtp_headers is a list of headers to be sent with the smtp message.

There are four ways to charge for messages:

subscriber_priority - charge per subscriber. If there are no available subscribers, the charge is per email. If there are no available mails, an error is returned.

credit_priority - charge per letter. If there are no available subscribers, the charge is per subscriber. If there are no available subscribers, an error is returned.

Subscriber - charge per subscriber. If there are no available subscribers, an error is returned.

Credit - charge per letter. If there are no available letters, an error is returned.

Let's explain some parameters of the server's json response to a request to send a single email message.

All parameters and their explanations are listed below:

There are six message statuses:

Queued - the message has been added to the queue

Sent - the message has been sent and is awaiting delivery confirmation.

Delivered - the message has been delivered

Skipped - the message has not been sent. The recipient has unsubscribed from your messages or is on the problem recipients list.

Soft_bounced - the message was not delivered. The recipient has temporarily bounced your message.

hard_bounced - the message could not be delivered for some reason.

Let's also look at the events.

There are four events:

Open - the message is read

Redirect - the recipient has followed the link

Spam - the recipient has marked your message as spam.

Unsubscribe - the user has unsubscribed from your messages.

Also note that if you send emails that are suspected as spam, you will receive error 429. This means that the number of messages you can send at a time is limited. This is to prevent spamming. If you only send to your customers, to existing email addresses, then the number of messages you can send per unit of time will increase; if your behaviour is suspicious, then vice versa.

You can also get some information about the message sent

To do this, you need to run a query:

curl -X GET https://api.msndr.net/v1/email/messages/1 \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'            \
     -d '...JSON...'

Uses the GET method and the link

/email/messages/:id

where ID is the identification number of the message returned by the server in the above response.

If the request is successful, you may receive the following response:

{
  "id":1,
  "from_email":"alice@example.org",
  "from_name":"Alice",
  "to":"bob@example.org",
  "subject":"Hello",
  "text":"Hello, Bob!",
  "html":"<h1>Hello, Bob!</h1>",
  "status":"queued",
  "events": {
    "open": 1,
    "redirect": {
      "http://foo.com": 2,
      "http://bar.com": 3
    },
    "spam": 1,
    "unsubscribe": 1
  }
}

attributes of the Json response from the server:

Id - message ID

from_email - sender's email address

from_name - sender's name

to - email address of the recipient

subject - message subject

text - text version of the message

html - html version of the message

status - message status

events - information about events related to this message.

Let's explain the message statuses that occur when responding to such requests:

Events that occur in response to such requests:

Sending a message based on a given template

First of all, you will need to create a template. To do this, in your personal account in the Automation section, select Single by template and create a message template. You can send emails according to this template with parameters. To do this, you need to substitute the necessary parameters in the template using the [%parameter name%] construct. For example like this:

[%name%], [%age%], etc.

Example of json data for such a request:

{
  "to": "bob@example.org",
  "payment": "credit",
  "params": {
    "name": "Ivan",
    "age": "33"
  }
}

An example of the query itself:

curl -X POST https://api.msndr.net/v1/email/templates/1/messages \
     -H 'Content-Type: application/json'        \
     -H 'Authorization: Bearer $API_TOKEN'      \
     -d '...JSON...'

POST method and link /email/templates/:template_id/messages

where template_id is the identification number of the template created in your personal account.

The request can take the following parameters:

Have you tried Cloud4U cloud services? Not yet?

Go to the Main Website

Try for free