Send Attachments

Attachments (an invoice PDF, a ticket, a report) are sent over SMTP. The HTTP Send API (POST /v1/send) carries text and HTML only; see What the HTTP API does not do.

What you need

A Motor Block of type transactional or general_purpose. Both send attachments. A marketing Motor Block cannot send over SMTP at all (campaign mail goes through the Communications Block).
SMTP credentials for that block: mail.motorical.com, port 2587 (STARTTLS) or 2465 (implicit TLS). Ports 587 and 465 are a different service. See Authentication methods.
A plan that includes attachments.

Who decides what is allowed

Two things decide, in this order:

Your plan decides whether attachments are allowed at all, how many per message, and the largest single file. These values change with the plans, so read them live and never copy them into code: GET https://motorical.com/api/billing/plans returns each plan's features.attachments (allowed, maxCount, maxSizePerFile in bytes).
The whole message must stay under 10 MB. This is a hard ceiling on the encoded message, whatever the plan says. Attachments are base64-encoded for transport, which adds about a third, so keep the total size of all files under roughly 7 MB. A per-file plan limit larger than that cannot be reached through SMTP today.

The Motor Block type does not change any of this for transactional and general_purpose: the same plan limits apply to both.

What counts as an attachment

Only real files count. These parts are always allowed and never count towards the plan's count or size limits:

inline images referenced from the HTML by Content-ID (a logo in a receipt)
calendar invitations (text/calendar)
cryptographic signatures and encryption parts (PGP, S/MIME)
delivery receipts

Dangerous file types are still screened by the content filter regardless of type.

Examples

Keep credentials in environment variables, never in source code.

Node.js
Python
PHP (PHPMailer)

const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'mail.motorical.com',
  port: 2587,
  secure: false,          // STARTTLS on 2587; use port 2465 with secure: true for implicit TLS
  requireTLS: true,
  auth: { user: process.env.MOTORICAL_SMTP_USER, pass: process.env.MOTORICAL_SMTP_PASSWORD },
});

await transporter.sendMail({
  from: 'billing@yourdomain.com',          // must be on the Motor Block's domain
  to: 'customer@example.com',
  subject: 'Your invoice',
  text: 'Your invoice is attached.',
  attachments: [{ filename: 'invoice-1001.pdf', path: './invoice-1001.pdf' }],
});

import os, smtplib
from email.message import EmailMessage

msg = EmailMessage()
msg["From"] = "billing@yourdomain.com"      # must be on the Motor Block's domain
msg["To"] = "customer@example.com"
msg["Subject"] = "Your invoice"
msg.set_content("Your invoice is attached.")
with open("invoice-1001.pdf", "rb") as f:
    msg.add_attachment(f.read(), maintype="application", subtype="pdf", filename="invoice-1001.pdf")

with smtplib.SMTP("mail.motorical.com", 2587) as smtp:
    smtp.starttls()
    smtp.login(os.environ["MOTORICAL_SMTP_USER"], os.environ["MOTORICAL_SMTP_PASSWORD"])
    smtp.send_message(msg)

<?php
use PHPMailer\PHPMailer\PHPMailer;

$mail = new PHPMailer(true);
$mail->isSMTP();
$mail->Host = 'mail.motorical.com';
$mail->Port = 2587;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->SMTPAuth = true;
$mail->Username = getenv('MOTORICAL_SMTP_USER');
$mail->Password = getenv('MOTORICAL_SMTP_PASSWORD');
$mail->setFrom('billing@yourdomain.com');   // must be on the Motor Block's domain
$mail->addAddress('customer@example.com');
$mail->Subject = 'Your invoice';
$mail->Body = 'Your invoice is attached.';
$mail->addAttachment('invoice-1001.pdf');
$mail->send();

Errors and what to do

The gateway answers during the SMTP conversation, so your library raises these as send errors.

Reply	Meaning	Fix
`550 Email rejected: Attachments not included in <plan>. Upgrade for attachment support.`	The plan does not include attachments.	Choose a plan with attachments.
`550 Email rejected: Too many attachments (N). <plan> allows max M attachments.`	More files than the plan allows.	Send fewer files per message, or combine them.
`550 Email rejected: Attachment "<name>" too large (<KB>KB). <plan> limit: <MB>MB per file.`	One file exceeds the plan's per-file limit.	Shrink or split the file.
`552 5.3.4 Message size exceeds limit (10MB)`	The whole encoded message is over 10 MB. This is permanent: retrying the same message will never work.	Keep the total of all files under about 7 MB, or send a download link instead.
`550 Email rejected: Attachments are not allowed on marketing motor blocks.`	Marketing blocks do not send attachments.	Use the Communications Block for campaigns.

What the HTTP API does not do

POST /v1/send accepts from, fromName, to (one address or a list of up to fifty), subject, text, html, headers and dryRun. It has no attachments and no cc or bcc fields. If a message needs a file or a copy to another recipient, send it over SMTP as above.

Through the headers object you can still set Reply-To, In-Reply-To, References, List-Unsubscribe and your own X- headers. A short list of headers that would let a message pretend to be someone else (From, Sender, Return-Path, To, Cc, Bcc, Subject, Date, Message-ID, the DKIM and authentication headers) is rejected.

What you need​

Who decides what is allowed​

What counts as an attachment​

Examples​

Errors and what to do​

What the HTTP API does not do​

Related​