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:
This is the url you'll POST your data to. Just fill in the domain portion with one you have configured in the dashboard.
To authenticate to our server include the "domain_key" header with a value of your API key for the domain you're sending from.
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.
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.
Before listing all the available API parameters it's helpful to lay out some general guidelines.
- Always keep time sensitive emails (reset password, 2FA, etc) as small as possible. Postagent processes messages under 200kb in a fast lane. We recommend under 10kb if possible to reduce processing time on the Mail Service Provider's (Gmail, AOL, etc) end.
- Even if our server accepts your mail it can still error when sent or be rejected by the recipient MTA/MDA. Make sure you have a server listening for our failure webhook events or enable logging.
- When mail fails to deliver we will retry up to five times over 3 days. You will be alerted via webhook of these retries.
- The maximum number of to, cc, bcc recipients combined is 50. If you need to send mass emails always use the batch API.
- The maximum size of the entire JSON payload must be less than 10mb. For example if your email body is 500kb that leaves you 9.5MB for attachments.
- You should never ignore suppressions unless it is an emergency, because it can harm your domain's sender reputation. Emergencies include alerting a user of an account change, financial activity, suspicious login, etc.
- Atleast one recipient across any of the to, cc, or bcc fields is required.
- You cannot declare the same recipient address more than once across to, cc, bcc.
- Always include a system that allows people to opt out of receiving your emails.
Should not be used unless the email is notifying the recipient of an emergency situation such as account compromise or financial activity.
<img src="cid:0"></img> here the "cid" is "0".
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.
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.
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.
PostAgent provides an ESMTP interface. The following extensions are available:
- SIZE 8000000
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!