Sending

Send Mail API

This page covers our APIs for sending standard email. If you need to send mailing lists or bulk mail use the batch API. Consider reading our introduction to email guide if you are new to email programming.

Should you send email with SMTP or HTTP?

We'll cover both, but you'll have to decide which is best for your application.

SMTP Pros & Cons

SMTP is a standard for sending email built into a lot of software already. This means you can plug in your PostAgent credentials and immediately begin sending mail. This makes it a good option if you want to be able to switch mail providers with no change to your code. The downside is that it's a complex and slow protocol.

Go to SMTP section

HTTP Pros & Cons

HTTP is the protocol everyone is familiar with. It's fast, easy to work with, and it's everywhere. The HTTP API is the best way to interface with PostAgent, but it will require you to write your own code, versus using prebuilt SMTP software.

Go to HTTP section

Sending with the HTTP API

Our API uses JSON to define the contents of emails. Even if you're unfamiliar with JSON you'll find it's easy to understand and parse with code. Let's jump right in and look at an example:

Request URL

1
POST
https://api.postagent.io/yourdomain.com/send

This is the url you'll POST your data to. Just fill in the domain portion with one you have configured in the dashboard.

Request Headers

1
Request Header
domain_key : your_api_key

To authenticate to our server include the "domain_key" header with a value of your API key for the domain you're sending from.

Request Body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"to": [
{
"email": "bilbo@shiremail.com" ,
"name": "Bilbo Baggins"
},
{
"email": "gandalf@shiremail.com" ,
"name": "Gandalf"
}
],
"from": {
"email": "sauron@mountdoom.org" ,
"name": "Sauron"
},
"subject": "The ring is mine",
"body": {
"html": "<b>Sauron the Great, bids thee welcome.</b>",
"text": "Sauron the Great, bids thee welcome."
}
}

Let's break this body down. We have two recipient objects in our "to" array, which means PostAgent will generate and send the email to two recipients (though in most cases you should use the batch API when sending to multiple recipients in one API call). We have a "from" object which defines who is sending the email. Our "subject" string sets the subject of the email. Finally, our "body" object defines the content of the email and can take a plain text object, a HTML object, or both.

Request Response

1
Response
{ HTTP/2 202 Accepted }

Your request is parsed for malformation, after which a response code is returned in real time. If your request is successful you will receive a status "202 Accepted" response. This indicates that we received the mail okay, but it could still error when actually sent to the recipient.

If the mail bounces or errors at the sender level you will receive a POST request to the webhook you have configured.

Guidelines

Before listing all the available API parameters it's helpful to lay out some general guidelines.

Available Parameters

Property name
Type
Required?
"headers"
Object
No
Allows you to define headers that the receiver clients can use.
"your_header_here"
String
No
Example: Someheader: my value. Max: 100 custom headers.Header key cannot contain reserved words: X-report-abuse, X-MTA-user, received, dkim-signature, MIME-Version, Message-id, Content-Type, Content-Disposition, Content-ID, Content-Transfer-Encoding, To, From, Date, Subject, Reply-To, CC, BCC
"ignore_suppression"
Boolean
No
Allows you to ignore suppressions if set to true.
Should not be used unless the email is notifying the recipient of an emergency situation such as account compromise or financial activity.
"defer_until_second"
Integer
No
Allows you schedule an email to be sent at a specific time denoted as a UNIX timestamp (seconds ex:1565132195). To optimize delivery and respect recipient SMTP server socket limits your scheduled mail may arrive +-5 minutes early/late. You can only schedule emails up to 6 days in advance.
"to"
Object Array
No
Contains mail recipients as objects. Max: 100 including cc + bcc.
"email"
String
Yes
Defines an address to receive the email.
"name"
String
No
Optional name for the recipient.
"cc"
Object Array
No
Contains mail recipients to Carbon Copy as objects. Max: 100 including to + bcc.
"email"
String
Yes
Defines an address to receive the email.
"name"
String
No
Optional name for the recipient.
"bcc"
Object Array
No
Contains mail recipients to Blind Carbon Copy as objects. Max: 100 including to + cc.
"email"
String
Yes
Defines an address to receive the email.
"name"
String
No
Optional name for the recipient.
"from"
Object
Yes
Contains the from object.
"email"
String
Yes
Defines the address of who sent the email. "From" domain should match the account domain you are sending from to prevent mail forging checks from failing at the recipient server.
"name"
String
No
Names who sent the email.
"reply_to"
Object
No
Contains who you want to receive replies to your email. Rarely used and not required but available for those who need it.
"email"
String
Yes
Defines an address you want to receive replies.
"name"
String
No
Optional name for replies.
"subject"
String
No
Defines the email subject.
"body"
Object
No
Contains the content of your email. Can contain both text & HTML values but must contain at least one or the other.
"html"
String
No
The content of the email as rich HTML formatted text.
"text"
String
No
The content of the email as plain text.
"attachments"
Object Array
No
Contains attachments as objects.
"type"
String
No
The MIME type of the attachment.
"filename"
String
No
The name of the attachment file.
"disposition"
String
No
Can contain a value of "attachment" or "inline" to declare how the attachment will be used in the email. If undeclared defaults to attachment.
"cid"
String
No
A unique value that can be used to reference the attachment when it's disposition is "inline". For example you could inline an attachment in your HTML body:
<img src="cid:0"></img> here the "cid" is "0".
"data"
String
Yes
A base64 encoded string containing the attachment data.
"track"
Object
No
Defines whether tracking should be enabled for the email. Tracking incurs additional charges.
"open"
String
No
If set, open tracking is enabled. Give a value of your campaign key.
"click"
String
No
If set, click tracking is enabled. Give a value of your campaign key.
"tls"
String
No
Can take a value of "strict" or "lax". Defaults to "strict". Under strict mode if a TLS connection cannot be established delivery will not proceed. In lax mode if a TLS connection cannot be established mail will be sent in plaintext. It's highly recommended to always use strict mode.

Sending mail with MIME

Currently we don't support this in the HTTP API. The HTTP API automatically handles encoding MIME when needed. To send encoded MIME you must use the SMTP API.

Sending Mail with SMTP (ESMTP)

If you want to send mail with SMTP it is supported based on RFC 5321.

If you plan to use the non-standard email operations we support such as open tracking, they must be defined as MIME headers in the "X-header" format.

X-header example

1
Mail Header
X-open-track: c258d700-9b11-4eac-9340-0f2a42aba253

Advanced header options: X-click-track, X-open-track. To track message opens use the X-open-track header. To track clicks use the X-click-track header. These headers are not relayed to the user. They are recorded internally and dropped from the header list at relay time.

Relaying considerations

Your messages are not relayed exactly as submitted. They will be decomposed, queued, then reconstructed and sent. Headers and content are forwarded identically, but changes in source syntax will occur.

Supported Extensions

PostAgent provides an ESMTP interface. The following extensions are available:

More examples

You've seen the entirety of the standard sending API's documentation now. Thanks for reading all that! Here on out we'll give you some examples you can copy paste. Best of luck with your project and don't hesitate to message us on Discord for help!