SMTPeter can generate and send messages based on JSON input. Theproperties in the JSON (like the subject and message body) are convertedinto a valid email message and sent to the recipient. This feature isespecially useful if you do not want to bother about setting up a MIMEstring yourself.
POST /v1/send?access_token={YOUR_API_TOKEN} HTTP/1.0Host: www.smtpeter.comContent-Type: application/jsonContent-Length: 7391{ "recipient": "john@doe.com", "subject": "This is a test mail", "from": "info@example.com", "text": "This is the messge body...", "html": "<html><head>..."}The following table lists all supported properties:
| Property | Description |
|---|---|
| from | "From:" header |
| to | "To:" header |
| cc | "Cc:" header |
| replyto | "Reply-To:" header |
| subject | Subject of the mail |
| text | Text version of the mail |
| html | HTML version of the mail |
| unsubscribe | The "list-unsubscribe" header |
| extra | Extra x-\* headers |
| attachments | Attachments to be added to the mail |
Address format
The "from", "to", "replyto" and "cc" fields can be used to add email addresses tothe message header. The "from" variable must be a single emailaddress, while there is no limit to the number of addresses that you usefor the "to", "replyto" and the "cc" fields.
The notation for the email addresses in the "from", "to", "replyto" and "cc" fieldsis very flexible: SMTPeter also recognizes display names and commaseparated lists of addresses.
{ "from": "info@example.com", "to": [ "one@example.com", "two@example.com", "\"Number three\" <three@example.com>, info@example.com" ], "cc": "John Doe <johndoe@example.org>"}Important: the addresses in "from", "to", "replyto" and "cc" are not used forthe e-mail delivery. You need a special "recipient" property for this.The "from", "to", "replyto" and "cc" are only used to create the content of the e-mailmessage, and it is thus in fact possible to create an e-mail with adifferent to-address than the address to which the mail is sent. For moreinformation about this, check out the article onsetting up the recipients.
Subject, text and HTML
The "subject", "text" and "html" properties can be used to set thesubject line of the email, and the text and HTML version. The propertiesare self-explanatory.
{ "subject": "this is the subject line", "html": "<html> .... </html>", "text": "text version of the email"}Unsubscribe header
If you want to add a "list-unsubscribe" header to your email, you canadd the JSON "unsubscribe" option. You can add either an URL or an email address,or both:
{ "subject": "this is the subject line", "html": "<html> .... </html>", "text": "text version of the e-mail", "unsubscribe": { "email": "unsubscribe@example.com", "url": "http://www.example.com" }}If your unsubscribe form complies with RFC 8058, you can add the "one-click" option to the "unsubscribe" settings. When using this option, an additional "list-unsubscribe-post" header is added to the email. This allows receiving software to recognize that the unsubscribe page distinguishes between "one-click" unsubscribes and regular unsubscribes. Please note that if you choose to use this option, your website's unsubscribe page must indeed adhere to this specification. Unsubscribes received via HTTP POST should be processed without further interaction, while for unsubscribes via HTTP GET, it is allowed to first display a confirmation page.
It is highly recommended to use this option because some recipients, including gmail.com, take this into account for deliverability. However, you need to first modify your website to distinguish between HTTP POST unsubscribes and HTTP GET unsubscribes before adding the "one-click" option to the JSON.
{ "subject": "this is the subject line", "html": "<html> .... </html>", "text": "text version of the e-mail", "unsubscribe": { "url": "http://www.example.com", "oneclick": true }}Extra "x-*" headers
The "extra" property can be used in case you want to add custom headersto your email. To ensure that your custom headers do not conflict withother headers, you may only add headers with a "x-*" prefix.
{ "subject": "this is the subject line", "html": "<html> .... </html>", "text": "text version of the email", "extra": { "x-my-identifier": "abcdefg", "x-custom-property": "custom" }}Attachments
With the "attachments" property you can attach files to your mailing. SMTPeterexpects an array with JSON objects. There are two types of objects that aresupported. For one you provide a link to the attachment that you wantto send and for the other you provide the data in the JSON object itself.If you provide the data in the JSON, this data has to be base64 encoded.Moreover, you can optionally specify the type of data that you send.
{ "attachments": [ { "url": "https://www.example.com/attachment1.pdf", "name": "attachment1.pdf", "type": "application/pdf" }, { "data": "VGhpcyBpcyBqdXN0IGFuIGV4YW1wbGUgdGV4dCBmaWxlLi4=", "name": "test.txt", "type": "text/plain" } ]}If all information is provided in a correct format you will get a reaction from the API.
More information
- REST API
- Send MIME data
- Send template based mails
- Advanced delivery options
