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:
| send | A simple function that accepts the necessary individual parameters and then will assemble the message for you and relay it via your account. |
| 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. |
| status | A function that reports your account status including expiry date, quote reset date, quota limits and quota usage. |
| quota_history | A 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 | |
|---|---|
| send | https://api.authsmtp.com/v2/send |
| send_formatted | https://api.authsmtp.com/v2/send_formatted |
| status | https://api.authsmtp.com/v2/status |
| quota_history | https://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:
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.
| NAME | TYPE | REQUIRED | FORMAT | NOTES |
|---|---|---|---|---|
| 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 | 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 | 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 ] | 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 ] | 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 ] | 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 | 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.
| NAME | TYPE | REQUIRED | FORMAT | DESCRIPTION |
|---|---|---|---|---|
| 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 | 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 | address1@example.com, address2@example.com, address3@example.com | 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.
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| 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.
| NAME | TYPE | DESCRIPTION |
|---|---|---|
| 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).
| NAME | FORMAT | DESCRIPTION |
|---|---|---|
| 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).
| NAME | DESCRIPTION |
|---|---|
| error_code | A numeric error code |
| error_subject | A longer description of the error that has occurred |
| error_description | A 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 CODE | DESCRIPTION |
|---|---|
| 500 | Envelope from address is not authorized |
| 502 | Header from address is not authorized |
| 428 | Your account is using SSL |
| 429 | Your account has expired |
| 556 | Message too large |
| 536 | ESMTP Message too large |
| 250 | Email contained a virus and was discarded |
| 426 | You account is currently disabled |
| 452 | Too many recipients |
| 432 / 441 | Account is at / over data quota |
| 433 / 443 | Account is at / over message quota |
| 434 / 435 / 440 / 442 | Your account has not yet been verified |
| 20000 | No credentials could be found with the request |
| 20100 | An error occurred while trying to verify your credentials - please contact us |
| 20110 | An error occurred while trying to verify your credentials - please contact us |
| 20120 | An error occurred while trying to verify your credentials - please contact us |
| 20020 | You have hit the API call request for the IP address: [ip_address] |
| 20030 | You have hit the API call request limit for the user: [user_id] |
| 20040 | JSON Data found in request - but it cannot be parsed. |
| 20050 | The account is disabled - if you think this in error please contact us. |
| 20070 | Your account has a legacy format - please contact us to rectify this. |
| 20160 | The credentials supplied with the request were not found to be valid. |
| 30000 | Element [element_name] is not set, and is mandatory. |
| 30002 | Payload is either missing or empty. |
| 30010 | Element [element_name] is empty, and is mandatory |
| 30020 | Element [element_name] is not an array, and is mandatory |
| 30030 | Element [element_name] is empty, and not a valid domain part |
| 30040 | Element [element_name] contains invalid characters for a domain part |
| 30050 | Element [element_name] is not set therefore is not valid |
| 30070 | Element [element_name] is not a valid email address |
| 30080 | Element [element_name] is not a valid address |
| 30090 | Element [element_name] not one of [members] |
| 30100 | Both 'envelope_from_address' and 'from_address' cannot be missing |
| 30110 | Element [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? |
| 30140 | The request is missing a body element. |
| 30150 | body[x]['content'] is missing or not set. |
| 30170 | You have hit the API error limit for the IP address: [ip_address] |
| 30180 | You have hit the API error limit for the user address: [user_id] |
API Limits
The following system limits apply:
| TYPE | LIMIT |
|---|---|
| Maximum simultaneous connections per IP | 5 |
| Maximum requests from a single user in 60 seconds | 500 |
| Maximum requests from a single IP within 60 seconds | 500 |
| Maximum errors from a single IP in 60 seconds | 100 |
| Maximum errors from a single user in 60 seconds | 100 |