inbound

README

This helper is a stand-alone module to help get you started consuming and processing Inbound Parse data.

Table of Contents

• Fields
• Example Usage
• Testing the Source Code
• Contributing

Fields

ParsedEmail.Envelope

ParsedEmail.Envelope.To and ParsedEmail.Envelope.From represent the exact email addresses that the email was sent to and the exact email address of the sender. There are no special characters and these fields are safe to use without further parsing as email addresses

ParsedEmail.ParsedValues

Please see SendGrid Docs to see what fields are available and preparsed by SendGrid. Use these fields over the Headers as they are parsed by SendGrid and gauranteed to be consistent

ParsedEmail.TextBody

this field will satisfy most cases. SendGrid pre-parses the body into a plain text string separated with \n

ParsedEmail.ParsedAttachments

populated only when processing the email with ParseWithAttachments(). Provides the following ease of use values

• File: full attachment for uploading or processing (see example to upload to s3)
• Size: file size, useful for filtering or setting upper limits to attachments
• Filename: copies the original filename of the attachment, if there is not one, it defaults to 'Untitled'
• ContentType: the type of file

ParsedEmail.Body

populated only when the raw option is checked in the SendGrid Dashboard. Provides the raw HTML body of the email, unless you need to record the exact unparsed HTML payload from the email client, you should use the parsed fields instead. The field is named Body for backward compatability

ParsedEmail.Attachments

populated only when the raw option is checked in the SendGrid Dashboard. This field is deprecated. Use ParsedAttachments instead which does not require the Raw setting, and provides parsed values to use and process the attachments

ParsedEmail.Headers

this field is deprecated. Use the SendGrid processed fields in ParsedValues instead. While it maintains its presence to avoid breaking changes, it provides raw, unprocessed headers and not all email clients are compatible. For example. these fields will be empty if the email cient is Outlook.com

Example Usage

package main

import (
	"fmt"
	"log"
	"net/http"

	"github.com/sendgrid/sendgrid-go/helpers/inbound"
)

func inboundHandler(response http.ResponseWriter, request *http.Request) {
	parsedEmail, err := ParseWithAttachments(request)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Print(parsedEmail.Envelope.From)

	for filename, contents := range parsedEmail.ParsedAttachments {
		// Do something with an attachment
		handleAttachment(filename, contents)
	}


	for section, body := range strings.Split(parsedEmail.TextBody, "\n") {
		// Do something with the email lines
	}


	// Twilio SendGrid needs a 200 OK response to stop POSTing
	response.WriteHeader(http.StatusOK)
}

// example of uploading an attachment to s3 using the Go sdk-2
func handleAttachment(parsedEmail *ParsedEmail) {
	for _, contents := range parsedEmail.ParsedAttachments {
			if _, err := sgh.Client.Upload(ctx, &s3.PutObjectInput{
				Bucket:               &bucket,
				Key:                  &uploadPath,
				Body:                 contents.File,
				ContentType:          aws.String(contents.ContentType),
      }
  }
}

func main() {
	http.HandleFunc("/inbound", inboundHandler)
	if err := http.ListenAndServe(":8000", nil); err != nil {
		log.Fatalln("Error")
	}
}

Testing the Source Code

Tests are located in the helpers/inbound folder:

• inbound_test.go

Learn about testing this code here.

Contributing

If you would like to contribute to this project, please see our contributing guide. Thanks!

Documentation

Index

• type EmailAttachment
• type ParsedEmail
  • func Parse(request *http.Request) (*ParsedEmail, error)
  • func ParseWithAttachments(request *http.Request) (*ParsedEmail, error)
  • func (email *ParsedEmail) Validate() error

Examples

• ParsedEmail (ParseHeaders)
• ParsedEmail (ParseRawEmail)

Types

type EmailAttachment

type EmailAttachment struct {
	File        multipart.File `json:"-"`
	Filename    string         `json:"filename"`
	Size        int64          `json:"-"`
	ContentType string         `json:"type"`
}

EmailAttachment defines information related to an email attachment

type ParsedEmail

type ParsedEmail struct {
	// Header values are raw and not pre-processed by SendGrid. They may change depending on the email client. Use carefully
	Headers map[string]string
	// Please see https://docs.sendgrid.com/for-developers/parsing-email/setting-up-the-inbound-parse-webhook to see the available fields in the email headers
	// all fields listed there are available within the headers map except for text which lives in the TextBody field
	ParsedValues map[string]string
	// Primary email body parsed with \n. A common approach is to Split by the \n to bring every line of the email into a string array
	TextBody string

	// Envelope expresses the exact email address that the email was addressed to and the exact email address it was from, without extra characters
	Envelope struct {
		From string   `json:"from"`
		To   []string `json:"to"`
	}

	// Attachments have been fully parsed to include the filename, size, content type and actual file for uploading or processing
	ParsedAttachments map[string]*EmailAttachment

	// Raw only
	Attachments map[string][]byte
	// accessed with text/html and text/plain. text/plain is always parsed to the TextBody field
	Body map[string]string
	// contains filtered or unexported fields
}

ParsedEmail defines a multipart parsed email Body and Attachments are only populated if the Raw option is checked on the SendGrid inbound configuration and are named for backwards compatability

Example (ParseHeaders)

headers := `
Foo: foo
Bar: baz
`
email := ParsedEmail{
	Headers:     make(map[string]string),
	Body:        make(map[string]string),
	Attachments: make(map[string][]byte),
	rawRequest:  nil,
}
email.parseHeaders(headers)
fmt.Println(email.Headers["Foo"])
fmt.Println(email.Headers["Bar"])

Output:

foo
baz

Example (ParseRawEmail)

rawEmail := `
To: test@example.com
From: example@example.com
Subject: Test Email
Content-Type: multipart/mixed; boundary=TwiLIo

--TwiLIo
Content-Type: text/plain; charset=UTF-8

Hello Twilio SendGrid!
--TwiLIo
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable

<html><body><strong>Hello Twilio SendGrid!</body></html>
--TwiLIo--
`
email := ParsedEmail{
	Headers:     make(map[string]string),
	Body:        make(map[string]string),
	Attachments: make(map[string][]byte),
	rawRequest:  nil,
}

if err := email.parseRawEmail(rawEmail); err != nil {
	log.Fatal(err)
}

for key, value := range email.Headers {
	fmt.Println(key, value)
}
fmt.Println(email.Body["text/plain; charset=UTF-8"])

Output:

To test@example.com
From example@example.com
Subject Test Email
Content-Type multipart/mixed; boundary=TwiLIo
Hello Twilio SendGrid!

func Parse

func Parse(request *http.Request) (*ParsedEmail, error)

Parse parses an email using Go's multipart parser and populates the headers, and body This method skips processing the attachment file and is therefore more performant

func ParseWithAttachments

func ParseWithAttachments(request *http.Request) (*ParsedEmail, error)

ParseWithAttachments parses an email using Go's multipart parser and populates the headers, body and processes attachments

func (*ParsedEmail) Validate

func (email *ParsedEmail) Validate() error

Validate validates the DKIM and SPF scores to ensure that the email client and address was not spoofed