feat: make subject nullable when specifying template slug

README.md

@@ -127,16 +127,25 @@ $response = $lettr->emails()->sendText(
     text: 'Plain text content',
 );
 
-// Template email
+// Template email (subject is optional — if omitted, the template must have a subject defined,
+// otherwise the API will return an error)
 $response = $lettr->emails()->sendTemplate(
     from: 'sender@example.com',
     to: 'recipient@example.com',
-    subject: 'Welcome!',
+    subject: null,
     templateSlug: 'welcome-email',
     templateVersion: 2,
     projectId: 123,
     substitutionData: ['name' => 'John'],
 );
+
+// Override the template subject
+$response = $lettr->emails()->sendTemplate(
+    from: 'sender@example.com',
+    to: 'recipient@example.com',
+    subject: 'Welcome!',
+    templateSlug: 'welcome-email',
+);
 ```
 
 ### Attachments
@@ -168,8 +177,10 @@ $response = $lettr->emails()->send(
     $lettr->emails()->create()
         ->from('sender@example.com')
         ->to(['recipient@example.com'])
-        ->subject('Your Order #{{order_id}}')
         ->useTemplate('order-confirmation', version: 1, projectId: 123)
+        // subject() is optional when using a template — if omitted, the template must have a subject
+        // defined, otherwise the API will return an error
+        ->subject('Your Order #{{order_id}}')
         ->substitutionData([
             'order_id' => '12345',
             'customer_name' => 'John Doe',

src/Builders/EmailBuilder.php

@@ -386,8 +386,8 @@ public function build(): SendEmailData
             throw new InvalidValueException('At least one recipient is required.');
         }
 
-        if ($this->subject === null) {
-            throw new InvalidValueException('Subject is required.');
+        if ($this->subject === null && $this->templateSlug === null) {
+            throw new InvalidValueException('Subject is required when not using a template.');
         }
 
         // Content is required unless using a template

src/Dto/Email/SendEmailData.php

@@ -19,7 +19,7 @@
     public function __construct(
         public EmailAddress $from,
         public EmailAddressCollection $to,
-        public Subject $subject,
+        public ?Subject $subject = null,
         public ?string $text = null,
         public ?string $html = null,
         public ?EmailAddressCollection $cc = null,
@@ -41,7 +41,7 @@ public function __construct(
      * @param  array{
      *     from: string|array{email: string, name?: string},
      *     to: array<string>,
-     *     subject: string,
+     *     subject?: string|null,
      *     text?: string|null,
      *     html?: string|null,
      *     cc?: array<string>|null,
@@ -66,7 +66,7 @@ public static function from(array $data): self
         return new self(
             from: $from,
             to: EmailAddressCollection::forRecipients($data['to']),
-            subject: new Subject($data['subject']),
+            subject: isset($data['subject']) ? new Subject($data['subject']) : null,
             text: $data['text'] ?? null,
             html: $data['html'] ?? null,
             cc: isset($data['cc']) ? EmailAddressCollection::from($data['cc']) : null,
@@ -95,9 +95,12 @@ public function toArray(): array
         $data = [
             'from' => $this->from->address,
             'to' => $this->to->toStrings(),
-            'subject' => (string) $this->subject,
         ];
 
+        if ($this->subject !== null) {
+            $data['subject'] = (string) $this->subject;
+        }
+
         if ($this->from->name !== null) {
             $data['from_name'] = $this->from->name;
         }

src/Services/EmailService.php

@@ -107,7 +107,7 @@ public function sendText(
     public function sendTemplate(
         string|EmailAddress $from,
         array|string $to,
-        string $subject,
+        ?string $subject,
         string $templateSlug,
         ?int $templateVersion = null,
         ?int $projectId = null,
@@ -118,9 +118,12 @@ public function sendTemplate(
         $builder = $this->create()
             ->from($from->address, $from->name)
             ->to(is_array($to) ? $to : [$to])
-            ->subject($subject)
             ->useTemplate($templateSlug, $templateVersion, $projectId);
 
+        if ($subject !== null) {
+            $builder->subject($subject);
+        }
+
         if ($substitutionData !== null) {
             $builder->substitutionData($substitutionData);
         }

tests/Unit/Dto/SendEmailDataTest.php

@@ -2,8 +2,10 @@
 
 declare(strict_types=1);
 
+use Lettr\Builders\EmailBuilder;
 use Lettr\Collections\EmailAddressCollection;
 use Lettr\Dto\Email\SendEmailData;
+use Lettr\Exceptions\InvalidValueException;
 use Lettr\ValueObjects\EmailAddress;
 use Lettr\ValueObjects\Subject;
 
@@ -80,6 +82,26 @@
         ->and($array['from_name'])->toBe('Sender Name');
 });
 
+test('can create SendEmailData without subject when using template', function (): void {
+    $data = SendEmailData::from([
+        'from' => 'sender@example.com',
+        'to' => ['recipient@example.com'],
+        'template_slug' => 'welcome-email',
+    ]);
+
+    expect($data->subject)->toBeNull();
+});
+
+test('toArray excludes subject when null', function (): void {
+    $data = SendEmailData::from([
+        'from' => 'sender@example.com',
+        'to' => ['recipient@example.com'],
+        'template_slug' => 'welcome-email',
+    ]);
+
+    expect($data->toArray())->not->toHaveKey('subject');
+});
+
 test('toArray excludes null optional fields', function (): void {
     $data = SendEmailData::from([
         'from' => 'sender@example.com',
@@ -99,3 +121,38 @@
         ->and($array)->not->toHaveKey('substitution_data')
         ->and($array)->not->toHaveKey('tag');
 });
+
+// EmailBuilder subject validation
+
+test('EmailBuilder requires subject when no template slug', function (): void {
+    expect(
+        fn () => EmailBuilder::create()
+            ->from('sender@example.com')
+            ->to(['recipient@example.com'])
+            ->html('<p>Hello</p>')
+            ->build()
+    )->toThrow(InvalidValueException::class, 'Subject is required when not using a template.');
+});
+
+test('EmailBuilder does not require subject when template slug is set', function (): void {
+    $data = EmailBuilder::create()
+        ->from('sender@example.com')
+        ->to(['recipient@example.com'])
+        ->useTemplate('welcome-email')
+        ->build();
+
+    expect($data->subject)->toBeNull()
+        ->and($data->templateSlug)->toBe('welcome-email');
+});
+
+test('EmailBuilder allows subject to be set alongside template slug', function (): void {
+    $data = EmailBuilder::create()
+        ->from('sender@example.com')
+        ->to(['recipient@example.com'])
+        ->subject('Override Subject')
+        ->useTemplate('welcome-email')
+        ->build();
+
+    expect((string) $data->subject)->toBe('Override Subject')
+        ->and($data->templateSlug)->toBe('welcome-email');
+});

tests/Unit/Services/EmailServiceTest.php

@@ -219,6 +219,22 @@ public function lastResponseHeaders(): array
         ->and($transporter->lastData)->not->toHaveKey('substitution_data');
 });
 
+test('sendTemplate helper without subject lets template define it', function (): void {
+    $transporter = new MockTransporter;
+    $transporter->response = ['request_id' => 'req_tpl3', 'accepted' => 1, 'rejected' => 0];
+
+    $service = new EmailService($transporter);
+    $service->sendTemplate(
+        from: 'sender@example.com',
+        to: 'recipient@example.com',
+        subject: null,
+        templateSlug: 'welcome-email',
+    );
+
+    expect($transporter->lastData['template_slug'])->toBe('welcome-email')
+        ->and($transporter->lastData)->not->toHaveKey('subject');
+});
+
 test('send includes quota from response headers', function (): void {
     $transporter = new MockTransporter;
     $transporter->response = ['request_id' => 'req_quota', 'accepted' => 1, 'rejected' => 0];