Go Email API - Documentation

Create and manage email addresses in GoLang. Send and receive emails and attachments in code and tests.

Quick links

• API documentation
• GitHub Repository
• Full method documentation
• Examples
• Guides

Common controllers

• EmailController to send and receive emails
• InboxController create email addresses
• WaitForController wait for emails to arrive

Tutorial

• Golang email library tutorial

Get started

MailSlurp is an email API that lets you create email addresses on demand then send and receive emails in code and tests. No MailServer is required.

This section describes how to get up and running with the Go client. To use another language or the REST API see the developer page.

See the examples page for code examples and use with common frameworks.

See the method documentation for a list of all functions.

Get an API Key

You need a free MailSlurp account to use the service. Sign up for a free account first.

Install

go get github.com/mailslurp/mailslurp-client-go

You may also need these dependencies:

go get golang.org/x/oauth2
go get golang.org/x/net/context
go get github.com/antihax/optional

MailSlurp's Go library uses /antihax/optional to wrap many parameters. Example usage looks like this:

waitOpts := &mailslurp.WaitForLatestEmailOpts{
    InboxId: optional.NewInterface(inbox2.Id),
    Timeout: optional.NewInt64(30000),
    UnreadOnly: optional.NewBool(true),
}

Initialize

To initialize the MailSlurp client first get an API Key. Then import the libraries:

import (
    "context"
    "github.com/mailslurp/mailslurp-client-go"
)

Then configure the client:

var apiKey = "your-mailslurp-client"

// create a context with your api key
ctx := context.WithValue(
    context.Background(),
    mailslurp.ContextAPIKey,
    mailslurp.APIKey{ Key: apiKey }
)

// create mailslurp client
config := mailslurp.NewConfiguration()
client := mailslurp.NewAPIClient(config)

Controllers are then available on the client instance and can be passed your context and options:

inbox, response, err := client.InboxControllerApi.CreateInbox(ctx, &mailslurp.CreateInboxOpts{})

Example

import (
    "context"
    "github.com/antihax/optional"
    mailslurp "github.com/mailslurp/mailslurp-client-go"
    "github.com/stretchr/testify/assert"
    "os"
    "testing"
    "encoding/base64"
)

// create a client and a context 
func createClient(t *testing.T) (*mailslurp.APIClient, context.Context) {
    // read mailslurp api key from environment variable
    var apiKey = os.Getenv("API_KEY")
    assert.NotEmpty(t, apiKey, "API KEY is empty")

    // create a context with your api key
    ctx := context.WithValue(
        context.Background(),
        mailslurp.ContextAPIKey,
        mailslurp.APIKey{Key: apiKey},
    )

    // create mailslurp client
    config := mailslurp.NewConfiguration()
    return mailslurp.NewAPIClient(config), ctx
}

func Test_CanCreateInbox(t *testing.T) {
    client, ctx := createClient(t)

    // call inbox controller to create an inbox
    opts := &mailslurp.CreateInboxOpts{}
    inbox, response, err := client.InboxControllerApi.CreateInbox(ctx, opts)

    assert.Nil(t, err)
    assert.Equal(t, response.StatusCode, 201)
    assert.NotNil(t, inbox.Id)
    assert.Contains(t, inbox.EmailAddress, "@mailslurp.com")
}

See the Method Documentation for more information or see the use cases below.

Common use cases

Use controllers to manage MailSlurp entities.

Create an inbox

Use the InboxController to manage inboxes. You can create email addresses in MailSlurp by creating an inbox:

opts := &mailslurp.CreateInboxOpts{}
inbox, response, err := client.InboxControllerApi.CreateInbox(ctx, opts)

The email address and ID are accessible on the Inbox:

assert.NotNil(t, inbox.Id)
assert.Contains(t, inbox.EmailAddress, "@mailslurp.com")

Inbox types

Inboxes can be either SMTP or HTTP type. Set the inbox type using the inboxType property. SMTP inboxes are handled by a custom mailserver and support a wide range of clients while HTTP inboxes use Amazon SES and don't support some older clients like Outlook. SMTP inboxes are recommended for public facing email addresses while HTTP inboxes are best for application testing. Please see the guide on types of inboxes for more information.

Send emails

To send emails first create an inbox then use the SendEmailOptions to configure the email.

sendEmailOptions := mailslurp.SendEmailOptions{
    To: []string{inbox.EmailAddress},
    Subject: "Test email",
    Body: "<h1>MailSlurp supports HTML</h1>",
    IsHTML: true,
}
opts := &mailslurp.SendEmailOpts{
    SendEmailOptions: optional.NewInterface(sendEmailOptions),
}
res, err := client.InboxControllerApi.SendEmail(ctx, inbox.Id, opts)

Here is another example:

sendOpts := &mailslurp.SendEmailOpts{
    SendEmailOptions: optional.NewInterface(mailslurp.SendEmailOptions{
        To:      []string{inbox2.EmailAddress},
        Subject: "Test subject",
        Body:    "Hello from inbox 1",
        Attachments: attachmentIds,
    }),
}

Receive emails

You can read emails in Go using the WaitForControllerApi:

// fetch the email for inbox2
waitOpts := &mailslurp.WaitForLatestEmailOpts{
    InboxId: optional.NewInterface(inbox2.Id),
    Timeout: optional.NewInt64(30000),
    UnreadOnly: optional.NewBool(true),
}
email, response, err := client.WaitForControllerApi.WaitForLatestEmail(ctx, waitOpts)

You can extract the content of an email for use in your tests or application using regex and the email body:

// can extract the contents
r := regexp.MustCompile(`Your code is: ([0-9]{3})`)
code := r.FindStringSubmatch(email.Body)[1]

Attachments

Attachments can be sent by first uploading an attachment then using the returned ID with send email options. See the AttachmentController to manage attachments.

func uploadAttachment(t *testing.T) []string {
    client, ctx := createClient(t)
    attachmentBytes := []byte{0}
    uploadOpts := mailslurp.UploadAttachmentOptions{
        Base64Contents: base64.URLEncoding.EncodeToString(attachmentBytes),
        ContentType:    "text/plain",
        Filename:       "test.txt",
    }
    attachmentIds, _, err := client.AttachmentControllerApi.UploadAttachment(ctx, uploadOpts)
    assert.Nil(t, err)
    return attachmentIds
}

func Test_CanSendEmail_AndReceive(t *testing.T) {
    client, ctx := createClient(t)
    opts := &mailslurp.CreateInboxOpts{}

    // create two inboxes
    inbox1, _, err := client.InboxControllerApi.CreateInbox(ctx, opts)
    inbox2, _, err := client.InboxControllerApi.CreateInbox(ctx, opts)

    assert.Nil(t, err)

    // upload attachments before send
    attachmentIds := uploadAttachment(t)

    // send a simple email from inbox 1 to inbox 2
    sendOpts := &mailslurp.SendEmailOpts{
        SendEmailOptions: optional.NewInterface(mailslurp.SendEmailOptions{
            To:      []string{inbox2.EmailAddress},
            Subject: "Test subject",
            Body:    "Hello from inbox 1",
            Attachments: attachmentIds,
        }),
    }

    _, err = client.InboxControllerApi.SendEmail(ctx, inbox1.Id, sendOpts)
    assert.Nil(t, err)

    // now receive the email at inbox 2
    waitForOpts := &mailslurp.WaitForLatestEmailOpts{
        InboxId:    optional.NewInterface(inbox2.Id),
        Timeout:    optional.NewInt64(30000),
        UnreadOnly: optional.NewBool(true),
    }
    email, _, err := client.WaitForControllerApi.WaitForLatestEmail(ctx,waitForOpts)
    assert.Nil(t, err)

    // access content
    assert.Equal(t, email.InboxId, inbox2.Id)
    assert.Contains(t, email.Subject, "Test subject")
    assert.Contains(t, email.Body, "Hello from inbox 1")

    // download the attachment as bytes
    downloadedBytes, _, err := client.EmailControllerApi.DownloadAttachment(ctx, email.Attachments[0], email.Id, nil)
    assert.Nil(t, err)
    assert.NotEmpty(t, downloadedBytes)
}

Next step

For more information see the source code on GitHub or documentation available at MailSlurp's developer page.