EmailOnDeck PRO API Documentation

Basic Flow

• Log into your EmailOnDeck PRO account
  • Go to the "My Account" page.
  • Copy your private API key.
  • Utilize the API via the commands below.
• If your EmailOnDeck PRO account expires, or is deactivated, you will no longer have access to the API.
• Max daily API calls: 25,000 (can increase upon upgrade)

Base API URL

Each API call requires the action "act" parameter and your private API key "token" parameter.

Parameters:

base-url:  https://api.emailondeck.com/api.php
token:     [Provide to you]
act:       create_email
           delete_email
           delete_email_domain
           delete_message
           delete_message_all
           list_email_addresses
           list_email_domains
           message_count
           message_count_domain
           message_count_email
           send_email
           view_email_headers
           view_raw_email

Example usage:

* can be POST or GET

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=[SEE-ABOVE]

Example usage (cURL):

curl "https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=list_email_domains"

curl -X POST https://api.emailondeck.com/api.php \
     -d token=[YOUR-PRIVATE-KEY] \
     -d act=create_email \
     -d domain=example.com

Authentication & Limits

• Your token is a 40-character alphanumeric private API key from the "My Account" page. Keep it secret.
• Send it as the token parameter on every call (GET or POST).
• Access requires an active account, an expired or deactivated account loses API access.

Common authentication / access errors:

Invalid action                            - unknown "act" value
Invalid token syntax                      - token is not 40 alphanumeric characters
Invalid token                             - token does not match an account
Invalid access - account expired          - account has expired or is deactivated
error: exceeded daily api call limit; ... - daily call limit reached

Response Format

• Most actions return plain text: a "success" / "success:" line, or an "error:" line.
• Only view_email_headers returns JSON; view_raw_email returns the raw message source.
• Always check whether the response begins with "error:" before parsing.

ACTION: create_email

Create a new email address.

Parameters:

handle:  (alphanumeric, or empty to auto generate)
domain:  (available domain, or empty to auto generate)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=create_email&handle=john&domain=example.com

Response:

On success: "success:" followed by email address
On error:   "error:" followed by error message

ACTION: delete_email

Delete email address and all associated messages.

Parameters:

email_address (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=delete_email&email_address=john@example.com

Response:

On success: "success"
On error:   "error:" followed by error message

ACTION: delete_email_domain

Delete all email addresses, and associated messages for a given email domain. This does not delete the domain itself.

Parameters:

domain (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=delete_email_domain&domain=example.com

Response:

On success: "success"
On error:   "error:" followed by error message

ACTION: delete_message

Delete a specific message.

Parameters:

msg_id (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=delete_message&msg_id=204

Response:

On success: "success"
On error:   "error:" followed by error message

ACTION: delete_message_all

Delete all messages for a specific email address.

Parameters:

email_address (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=delete_message_all&email_address=john@example.com

Response:

On success: "success"
On error:   "error:" followed by error message

ACTION: list_email_addresses

List all email addresses for a specific domain.

Parameters:

domain (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=list_email_addresses&domain=example.com

Response:

On success: "success:" followed by email addresses in CSV format
On error:   "error:" followed by error message

ACTION: list_email_domains

List all available email domains.

Parameters:

order (alpha_asc, alpha_desc, date_asc, date_desc, or empty for alpha_asc)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=list_email_domains&order=date_desc

Response:

On success: "success:" followed by available email domains in CSV format
On error:   "error:" followed by error message

ACTION: message_count

Total number of messages in entire account.

Parameters:

n/a

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=message_count

Response:

On success: "success:" followed by the number of messages
On error:   "error:" followed by error message

ACTION: message_count_domain

Total number of messages for an email domain.

Parameters:

domain (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=message_count_domain&domain=example.com

Response:

On success: "success:" followed by the number of messages
On error:   "error:" followed by error message

ACTION: message_count_email

Total number of messages for an email address.

Parameters:

email_address (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=message_count_email&email_address=john@example.com

Response:

On success: "success:" followed by the number of messages
On error:   "error:" followed by error message

ACTION: send_email

Unavailable via API. Listed here purely as informational

Parameters:

n/a

Example usage:

n/a

Response:

n/a

ACTION: view_email_headers

View all message headers for a given email address.

Parameters:

email_address (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=view_email_headers&email_address=john@example.com

Response:

On success: JSON with message headers
            * Message Headers JSON:
              * msg_id:   The message ID
              * received: The time message was received by the server
              * from:     The message FROM address
              * subject:  The message SUBJECT
              * success:  "no messages found" - if no messages found
On error:   "error:" followed by error message

ACTION: view_raw_email

View the raw email for a specific message.

Parameters:

msg_id (required)

Example usage:

https://api.emailondeck.com/api.php?token=[YOUR-PRIVATE-KEY]&act=view_raw_email&msg_id=204

Response:

On success: The raw full email message
On error:   "error:" followed by error message