Email and Email Archives

An Introduction To Email

Here we share how to send an email, or retrieve details of past emails that have been sent.

There are two ways to send emails through the API; Standard Email (/email/send) and MIME Email (/email/mime) .

When using our View and Search Sent Emails endpoint, the filter_query field utilizes a subset of the Whoosh API which can be used to create complex filters to make searching more efficient. Scroll down for details on making use of this.

Finally, note that archived content and emails is accessed through the ARCHIVE EMAILS end point.

Standard Email; JSON Objects

With the /email/send endpoint, you pass us all of the components of an email, such as the sender, title, body and recipient as a JSON Object. We then create the email and send it.

This is the preferred method.

The /email/send endpoint allows you to make use of email templates; see examples for use of this your request.

The /email/send endpoint also accepts a version parameter (with a value of 1 or 2). Below are the structures of either version.

Version 1

mixed
- alternative
  - text
  - related
    - html
    - inline 1
    - inline ...
- attachment 1
- attachment ...

Version 2

mixed
- related
  - alternative
    - text
    - html
  - inline 1
  - inline ...
- attachment 1
- attachment ...

MIME Email

Alternatively, you may send an email composed as a MIME string. This can be done using a MIME library in your programming language of choice, before sending this to SMTP2GO via the 'Send a MIME Email' endpoint. SMTP2GO will use this exact MIME string to send the email.

Powerful Search with filter_query

The filter_query field utilizes a subset of the Whoosh API which can be used to create complex filters to make searching more efficient.

A query is broken up into terms and operators. There are two types of terms: Single Terms and Phrases.

A Single Term is a single word such as "test" or "hello".
A Phrase is a group of words surrounded by double quotes such as "hello dolly".

Multiple terms can be combined together with Boolean operators to form a more complex query; the API supports all boolean operators like AND, OR, and NOT.

If you want to search a specific field, use the field name followed by a colon and then your search term or phrase. The following fields are indexed and can be used for search:

Field Name	Description
sender sent_ts recipient subject delivered_ts status email_id smtpcode host headers	The sender/from email address. Unix timestamp the message was sent. The recipient email address(s). The Subject header. Unix timestamp the message reached its destination. One of the Delivery Statuses listed below. A unique identifier of the email. Response code from destination SMTP server. The destination host. The headers of the email.

Delivery Status Keywords
Where multiple keywords exist they can be used interchangeably.

failed - Delivery failed.
deferred - Delivery temporarily failed.
hardbounce, refused - Email rejected by destination MX.
softbounce, returned - Email returned after delivery.
delivered, ok, sent - Email accepted by destination MX.
rejected - Email rejected.
unsubscribed - Recipient used unsubscribe link.
complained, spam - Recipient made spam complaint.
unblocked - Unsubscribe cancelled.

Example

Search messages that contain 'welcome' or 'bienvenidos' in the subject line.

subject:welcome OR subject:bienvenidos

Header Searching
Any email header can be searched. The search must be exact, as part matches won't be returned.

This query must also be a Phrase surrounded by single quotes.

headers:'X-ExampleCustomHeader: Exact String to Match'
In order to search for multiple headers you must separate the header searches with a semi-colon character.

headers:'X-ExampleCustomHeader: Exact String to Match; X-OfficeId: headquarters;'

Continue Token
The continue_token field, if returned in the response of a search request, indicates that results exceeding the limit (either passed in the request, or the default value) are available.

In the event that you receive a continue_token string, you can pass it along with all of the original request data to continue the search and retrieve the next batch of results. In the event of multiple search batches, the continue_token will change for each request, so be sure the latest one should always be passed, otherwise you will continue to receive the same batch of results.

Accessing Archived Content

Email content which has been archived can be searched and retrieved using the /archive/search and /archive/email endpoints.

The /archive/search allows you to search your archived emails, returning a collection based on the parameters you pass. You can choose to include a limit, else a maximum default of 5,000 items will be returned.

The /archive/email allows you to target a specific email, by email_id, returning the data associated with the email; sender, recipient, subject, etc.