AuthSMTP RESTful API v2.0 [ BETA TEST ]

IMPORTANT NOTICE - Form URL Encoded requests / responses have now been deprecated and will not be supported in any new end points or features, only JSON formatted requests should be used.

Index

Overview

Version 2 of the AuthSMTP API supports message submission and is available as a BETA service to all users.

Initially, it will only include the ability to send messages and report account status, we are working to add additional functions such as delivery status and other account data.

Features

The API currently has the followingt endpoints:

sendA simple function that accepts the necessary individual parameters and then will assemble the message for you and relay it via your account.
send_formattedA lower level function that will allow you to assemble the message headers and body yourself and submit it for relay via your account.
statusA function that reports your account status including expiry date, quote reset date, quota limits and quota usage.
quota_historyA function that reports your account quota history including message and data usage, bounce rate, spam complaints and error counts.

The API also includes a sandbox option so you can test your code without actually sending any messages.

Key Information

CONNECTION PARAMETERS
API Host Name:https://api.authsmtp.com/v2/
API Port:443
HTTP Request Type:POST   (GET / PUT not supported)
HTTP Request Encoding:JSON Object or Form URL Encoded (deprecated)
ENDPOINT URLS
sendhttps://api.authsmtp.com/v2/send
send_formattedhttps://api.authsmtp.com/v2/send_formatted
statushttps://api.authsmtp.com/v2/status
quota_historyhttps://api.authsmtp.com/v2/quota_history

Authentication

All API requests must include the correct authentication credentials which consists of your account user name and your account API key.

API User Name:The API user name is the same as the control panel user name (e.g. ac10000).
API Key:The API key is a long randomly generated string which is set / unset via the control panel.

The credentials can be supplied in three ways:

  • Using HTTP BASIC Authentication
  • Include 'user_id' and 'api_key' fields within your API request body
  • Include a 'X-Credentials:' header in your request in the format of 'X-Credentials: user_id/api_key' ( Recommended ).

Customize Code Examples

This page contains a number of command line and code examples - if you complete the following details, we will customize all code examples for you:

 The code examples will be updated using JavaScript within your browser, they will not be transmitted.

Getting Started

If you have access to a command line with cURL access, you can run the following commands to send a quick test message or get your account status.

Please complete the Customize Code Examples Form and the code will be updated to use your details so you will be able to run it straight away from your computer.

'send' using JSON object and X-Header authentication (plain text body)
'send' using JSON object and X-Header authentication (HTML body) (recommended method)
'send_formatted' using a JSON object and body fields authentication
'send_formatted' using Form URL Encoding and HTTP BASIC authentication (deprecated)
'status' using X-Header authentication
'quota_history' using X-Header authentication

Code Examples

The following code examples are simple but working demonstrations of using the API with PHP.

Please complete the customize code examples form and the code will be updated to use your details.

If you have any issue running the example code, modify the value of 'CURL_DEBUG' at the top of the script to 'TRUE' and further information will be provided.

PHP CODE EXAMPLES
'send' using JSON object and X-Header authentication (HTML Body)
'send' using JSON object and X-Header authentication (HTML Body + In-line Image)
'send' using JSON object and X-Header authentication (HTML Body + Image Attachment)
'send_formatted' using JSON object and X-Header authentication (HTML Body)
'status' using JSON object and X-Header authentication
'quota_history' using JSON object and X-Header authentication

Endpoint Reference

The following sections document all the available fields that can be used with each end point:

Endpoint: send

A simple function that accepts the necessary individual parameters and then will assemble the message for you and relay it via your account.

NAMETYPEREQUIREDFORMATNOTES
sandbox bool optional true or false Option to enable the API sandbox, setting this option to 'true' means any the corresponding message will be validated in the same way as normal but the message will be discarded rather than attempting delivery. No messages or data will be deducted from your quota.
envelope_from_address email optional RFC email address Used as the envelope from address.

Also known as the MAIL-FROM or RETURN-PATH address.

If blank, will be populated using value of 'from_address'.

If neither are populated an error will be triggered.
from_address email optional RFC email address Used as the email address value in the 'From:' field of the email headers.

If blank, will be populated using the value of 'envelope_from_address'.

If neither are populated an error will be triggered.
from_name string optional RFC display name Used as the display name value in the 'From:' field of the email headers.
message_id string optional RFC message ID Will be used as the value in the 'Message-ID: field of the email headers.

Must be unique for each message.

If not populated, a system generated one will be assigned (recommended).
to array [ object ] optional Used to populate the RCPT TO: and 'To:' email header field.

Multiple recipients can be added within the array / object.
to [ address ] email required RFC email address Used to populate the RCPT TO: and 'To:' email header field
to [ name ] string optional RFC display name Used to populate the 'To:' email header field.
cc array [ object ] optional Used to populate the RCPT TO: and 'CC:' email header field.

Multiple CC recipients can be added within the array / object
cc [ address ] email required RFC email address Used to populate the RCPT TO: and 'CC:' email header field
cc [ name ] string optional RFC display name Used to populate the 'CC:' email header field
bcc array [ object ] optional Used to populate the RCPT TO: and 'BCC:' email header field.

Multiple BCC recipients can be added within the array / object.
bcc [ address ] email required RFC email address Used to populate the RCPT TO: and 'BCC:' email header field
bcc [ name ] string optional RFC display name Used to populate the 'BCC:' email header field.
reply_to_address email optional RFC email address Will be used as the value in the 'Reply-To: field of the email headers.

If blank, will be populated using the value of 'envelope_from_address'
reply_to_name string optional RFC display name Used as the display name value in the 'Reply-To:' field of the email headers if 'reply_to_address' is set.
header array [ object ] optional Used for adding custom email headers.

Multiple custom headers can be added within the array / object
header [ name ] string required Field name for custom email header
header [ value ] string required Field value for custom email header
subject string required Declare the email subject line
legacy_text string optional "You should not be able to see this - your email client is out of date and needs upgrading" Will be displayed in old legacy email clients that cannot process or understand MIME encapsulated emails
body array [ object ] required Used for adding the message body.

It is recommended that you add both plain text and HTML version of your message.
body [ type ] string required "text/plain"
"text/html"
Declare whether the body is plain text or HTML.

Only the syntax above can be used.
body [ encoding ] string optional
[ default: "7bit" ]
"base64"
"quoted-printable"
The encoding type used in the body part.
8bit should not be used due to compatibility issues with DKIM signing.
body [ charset ] string optional
[ default: "us-ascii" ]
"utf-8"
"us-ascii"
"iso-8859-1"
The character set used in the body part
body [ content ] string required The plain text / HTML body of the message.

Must end with a Carriage Return / Line Feed (\r\n), will be added if missing.
attachment array [ object ] optional Used for adding message attachments.

Multiple attachments can be added within the array / object.
attachment [ type ] string required 'text/plain'
'text/html'
'image/png'
'image/gif'
Declare the attachment type
attachment [ name ] string required The filename of the attachment.
attachment [ base64_data ] string required The base64 encoded body of the attachment.
attachment [ disposition ] string required inline or attachment Declare the content disposition of attachment.
attachment [ content_id ] string optional Used as a reference to in-line images, should start and end with chevrons.
e.g. <img src="cid:company-logo">

Endpoint: send_formatted

A lower level function that will allow you to assemble the message headers and body yourself and submit it for relay via your account.

NAMETYPEREQUIREDFORMATDESCRIPTION
sandbox bool optional true or false Option to enable the API sandbox, setting this option to 'true' means any the corresponding message will be validated in the same way as normal but the message will be discarded rather than attempting delivery. No messages or data will be deducted from your quota.
user_id string optional acXXXXX Your account user name.

Only required if you are authenticating using this method
api_key string optional Your account API key.

Only required if you are authenticating using this method
envelope_from_address email required RFC email address Your email from address, this field is also generally known as the RETURN-PATH or MAIL-FROM address.

Must be an email address only, no display name or additional text / symbols.
envelope_recipients email(es) required [email protected], [email protected], [email protected] Comma separated list of RFC compliant email addresses.

Must be a string of email addresses only, no display names or additional text / symbols
message string required The full message headers and body Must be a fully formed message including all necessary headers

Endpoint: status

A function that will return your account status including expiry date, quote reset date, quota limits and quota usage.

NAMETYPEDESCRIPTION
messages_remaining integer Number of messages remaining in current quota period
bytes_remaining integer Number of bytes remaining in current quota period
account_expiry_date YYYY-MM-DD HH:MM:SS The current expiry date of your account
account_level string Your current account level
next_quota_reset YYYY-MM-DD HH:MM:SS The date and time at which your monthly quota will next reset
api_current integer How many API calls you have made the in current limit period
api_limit integer How many calls you can make in current limit period
api_limit_expiry integer How long the current period is in seconds
api_limit_ttl integer How many seconds until the limit resets

Endpoint: quota_history

A function that will return your account's quota history for each period for up to the last 12 months.

NAMETYPEDESCRIPTION
period integer Numeric index for the quota period, the results start with the current quota period using an index of '0', the previous period will have an index of '-1' and so on
byte_count integer Number of bytes sent in the quota period
msg_count integer Number of messages sent in the quota period
spam_count integer Number of automated spam complaints received against messages sent in the quota period
bounce_count integer The number of messages that could not be delivered in the quota period (i.e. bounces)
error_count integer The number of errors logged against your account in the quota period. Errors occur when your application attempts to submit a message to our network but it cannot be accepted (e.g insufficient quota, from address not authorized etc)
virus_count integer The number of messages rejected by our anti-virus scanning engine in the the quota period.
end_date YYYY-MM-DD HH:MM:SS The end date and time of the quota period
start_date YYYY-MM-DD HH:MM:SS The start date and time of the quota period

Success Responses

If your request is successful and the message has been accepted, the API will return a standard HTTP response with a status code of "HTTP/1.1 200 OK" and the response body will contain data about your message submission and updated quota data.

The format of the success response body will match your request format which will either be a JSON object or Form URL Encoded (deprecated).

NAMEFORMATDESCRIPTION
message_uuid string A unique message ID assigned by our network
messages_remaining integer The number of messages remaining from your quota in the current quota period
bytes_remaining integer The amount of data (in bytes) remaining from your quota in the current quota period
next_quota_reset YYYY-MM-DD HH:MM:SS The date and time at which your monthly quota will next reset

EXAMPLE JSON RESPONSE:

Error Responses

You should ensure that your code is able to gracefully handle errors in not being able to transmit messages to our network. While we endeavour to provide maximum availability for our service there is always the possibility of connectivity or other technical issues beyond our (or your) control. Ideally error handling, logging, message queueing (with retry) and monitoring should all be considered.

If your request is unsuccessful, the API will return a standard HTTP response with a status code of "HTTP/1.1 406 Not Acceptable" and the response body will contain data detailing the error that occurred.

The format of the error response body will match your request format which will either be a JSON object or Form URL Encoded (deprecated).

NAMEDESCRIPTION
error_codeA numeric error code
error_subjectA longer description of the error that has occurred
error_descriptionA longer description of the error that has occurred

EXAMPLE JSON RESPONSE:

Error Codes

Here is a list of possible error codes and their causes:

ERROR CODEDESCRIPTION
500Envelope from address is not authorized
502Header from address is not authorized
428Your account is using SSL
429Your account has expired
556Message too large
536ESMTP Message too large
250Email contained a virus and was discarded
426You account is currently disabled
452Too many recipients
432 / 441Account is at / over data quota
433 / 443Account is at / over message quota
434 / 435 / 440 / 442Your account has not yet been verified
20000No credentials could be found with the request
20100An error occurred while trying to verify your credentials - please contact us
20110An error occurred while trying to verify your credentials - please contact us
20120An error occurred while trying to verify your credentials - please contact us
20020You have hit the API call request for the IP address: [ip_address]
20030You have hit the API call request limit for the user: [user_id]
20040JSON Data found in request - but it cannot be parsed.
20050The account is disabled - if you think this in error please contact us.
20070Your account has a legacy format - please contact us to rectify this.
20160The credentials supplied with the request were not found to be valid.
30000Element [element_name] is not set, and is mandatory.
30002Payload is either missing or empty.
30010Element [element_name] is empty, and is mandatory
30020Element [element_name] is not an array, and is mandatory
30030Element [element_name] is empty, and not a valid domain part
30040Element [element_name] contains invalid characters for a domain part
30050Element [element_name] is not set therefore is not valid
30070Element [element_name] is not a valid email address
30080Element [element_name] is not a valid address
30090Element [element_name] not one of [members]
30100Both 'envelope_from_address' and 'from_address' cannot be missing
30110Element [element_name] is not 7bit pure - and has to be.
30120'reply_to_name' is populated but corresponding 'address' is not.
30130[element_name] is empty?
30140The request is missing a body element.
30150body[x]['content'] is missing or not set.
30170You have hit the API error limit for the IP address: [ip_address]
30180You have hit the API error limit for the user address: [user_id]

API Limits

The following system limits apply:

TYPELIMIT
Maximum simultaneous connections per IP5
Maximum requests from a single user in 60 seconds500
Maximum requests from a single IP within 60 seconds500
Maximum errors from a single IP in 60 seconds100
Maximum errors from a single user in 60 seconds100